> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notte.cc/llms.txt
> Use this file to discover all available pages before exploring further.
# Cookies
> Persist authentication and manage cookies across sessions
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
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`:
{/* @sniptest testers/sessions/capabilities/automatic_persistence.py */}
```python automatic_persistence.py theme={null}
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.
## Manual Cookie Management
For more control, use `set_cookies()` and `get_cookies()`:
{/* @sniptest testers/sessions/capabilities/manual_cookie_management.py */}
```python manual_cookie_management.py theme={null}
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:
{/* @sniptest testers/sessions/upload_cookies.py */}
```python upload_cookies.py theme={null}
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:
```json theme={null}
[
{
"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:
{/* @sniptest testers/sessions/extract_cookies_manual.py */}
```python extract_cookies_local.py theme={null}
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:
{/* @sniptest testers/sessions/extract_cookies_notte.py */}
```python extract_cookies_notte.py theme={null}
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
Configure sessions with all options
Persist full browser state
Secure credential storage
Manage session states