> ## Documentation Index
> Fetch the complete documentation index at: https://notte-experiment-visibility-md-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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`:
{/* @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