Skip to main content
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: 
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"]', "user@example.com")
    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.
For more control, use set_cookies() and get_cookies(): 
from notte_sdk import NotteClient
import json

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 notte_sdk import NotteClient

# Upload cookies for github.com to automatically login
cookies = [
    dict(
        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) # 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()
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 Chrome, Firefox, or other browsers:
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
from notte_sdk import NotteClient
import json

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

IssueSolution
Session not authenticatedVerify cookies haven’t expired
Cookies not loadingCheck JSON format is valid
Partial authenticationEnsure all required cookies are included
Domain mismatchVerify 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