Cookies

Persist authentication and manage cookies across sessions

Cookies allow you to persist authentication state across sessions, avoiding repeated logins and maintaining session continuity.

Automatic Persistence

The simplest approach is automatic cookie persistence using cookie_file:

automatic_persistence.py

from notte_sdk import NotteClient

client = NotteClient()

# Cookies automatically loaded at start, saved when session ends
with client.Session(cookie_file="cookies.json") as session:
    page = session.page
    page.goto("https://example.com/login")

    # Log in once, cookies are captured
    page.fill('input[name="email"]', "[e-mail]")
    page.fill('input[name="password"]', "password")
    page.click('button[type="submit"]')

# Next time: already logged in!
with client.Session(cookie_file="cookies.json") as session:
    page = session.page
    page.goto("https://example.com/dashboard")
    # Authentication persisted from previous session

The cookie_file parameter handles everything automatically - loading cookies when the session starts and saving them when it ends.

Manual Cookie Management

For more control, use set_cookies() and get_cookies():

manual_cookie_management.py

import json

from notte_sdk import NotteClient

client = NotteClient()

# Save cookies from a session
with client.Session() as session:
    page = session.page
    page.goto("https://example.com")

    # Perform login...

    # Get and save cookies
    cookies = session.get_cookies()
    with open("cookies.json", "w") as f:
        json.dump(cookies, f)

# Load cookies in a new session
with client.Session() as session:
    with open("cookies.json", "r") as f:
        cookies = json.load(f)
    session.set_cookies(cookies=cookies)

    page = session.page
    page.goto("https://example.com/dashboard")
    # Already authenticated

Uploading Cookies

Upload cookies from an existing file:

upload_cookies.py

from typing import Any

from notte_sdk import NotteClient

# Upload cookies for github.com to automatically login
cookies: list[dict[str, Any]] = [
    {
        "name": "sb-db-auth-token",
        "value": "base64-cookie-value",
        "domain": "github.com",
        "path": "/",
        "expires": 9778363203.913704,
        "httpOnly": False,
        "secure": False,
        "sameSite": "Lax",
    }
]
# create a new session
client = NotteClient()
with client.Session() as session:
    _ = session.set_cookies(cookies=cookies)  # type: ignore[arg-type]  # can also set cookie_file="path/to/cookies.json"

    # Use the cookies in your session
    agent = client.Agent(session=session, max_steps=5)
    res = agent.run(
        task="go to nottelabs/notte get repo info. Fail if you are not logged in",
        url="https://github.com/nottelabs/notte",
    )

    # or get the cookies from the session
    cookies_resp = session.get_cookies()

Cookie File Format

Cookies must be a valid JSON array:

[
  {
    "name": "session_id",
    "value": "abc123",
    "domain": ".example.com",
    "path": "/",
    "expires": 1735689600,
    "httpOnly": true,
    "secure": true
  }
]

Extracting Cookies

From Your Browser

Export cookies from your browser:

extract_cookies_local.py

import json
from pathlib import Path

from patchright.sync_api import sync_playwright

cookie_path = Path("github_cookies.json")
# Initialize Playwright
with sync_playwright() as playwright:
    browser = playwright.chromium.launch(headless=False)
    context = browser.new_context()
    page = context.new_page()

    # Navigate to login page
    github_login_url = "https://github.com/login"
    page.goto(github_login_url)

    print("Please log into GitHub in the browser window...")
    input("Press Enter after you've logged in...")

    # Save cookies to file
    print("Login successful. Saving cookies...")
    cookies = context.cookies(urls=["https://github.com"])

    if cookies:
        cookie_path.write_text(json.dumps(cookies, indent=4))
        print(f"Cookies saved to {cookie_path}")
    else:
        print("No cookies found to save.")

From a Notte Session

Extract cookies programmatically:

extract_cookies_notte.py

import json

from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    # Observe the state of a webpage
    obs = session.observe(url="https://google.com/travel/flights")

    # Get and save cookies from the session
    with open("cookies.json", "w") as f:
        cookies = session.get_cookies()
        json.dump(cookies, f)

Best Practices

Security

• Store cookie files securely outside version control
• Add *.json cookie files to .gitignore
• Rotate cookies regularly for sensitive services
• Use environment-specific cookie files

Maintenance

• Monitor cookie expiration dates
• Set up automated refresh for long-running systems
• Keep backup copies of valid cookies

Troubleshooting

Issue	Solution
Session not authenticated	Verify cookies haven’t expired
Cookies not loading	Check JSON format is valid
Partial authentication	Ensure all required cookies are included
Domain mismatch	Verify cookie domains match target site

Next Steps

Session Configuration

Configure sessions with all options

Browser Profiles

Persist full browser state

Vaults

Secure credential storage

Session Lifecycle

Manage session states