Session Configurations

Learn how to create and configure Notte browser sessions

Sessions are isolated browser instances running in the cloud that you can control programmatically. Each session provides a Playwright-compatible page that you can automate using familiar browser automation APIs.

Quick Start

Create a session with default settings:

Python

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    print(f"Session ID: {session.session_id}")
    page = session.page  # Playwright-compatible page
    page.goto("https://example.com")

Active sessions can be viewed and managed in the Sessions page in the console.

Sessions are automatically stopped when exiting the context manager. Always use the with statement to ensure proper cleanup.

Configuration Options

Customize your session with these options:

Python

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(
    headless=True,
    solve_captchas=True,
    proxies=True,
    viewport_width=1920,
    viewport_height=1080,
    timeout_minutes=10,
    browser_type="chromium"
) as session:
    page = session.page
    page.goto("https://example.com")

Common Parameters

headless · boolean · default: true

Whether to run the browser in headless mode. Set to false to open a live viewer in your browser.

solve_captchas · boolean · default: false

Automatically detect and solve captchas (reCAPTCHA, hCaptcha, etc.)

proxies · boolean | list[ProxySettings] · default: false

Enable residential proxies. Set to true for default proxies or provide custom proxy configuration. See Proxy Configuration for details.

timeout_minutes · integer · default: 3

Session timeout in minutes. Sessions automatically close after this duration (min: 1, max: 30).

viewport_width · integer · default: 1280

Browser viewport width in pixels.

viewport_height · integer · default: 1080

Browser viewport height in pixels.

browser_type · string · default: "chrome"

Browser engine to use: "chromium", or "chrome".

Advanced Parameters

user_agent · string

Custom user agent string for the browser session.

chrome_args · list[str]

Custom Chrome/Chromium launch arguments. Advanced use only.

cdp_url · string

Connect to an external browser session via Chrome DevTools Protocol URL (e.g., from Kernel.sh or other providers).

use_file_storage · boolean · default: false

Enable file storage for uploading/downloading files during the session.

cookie_file · string | Path

Path to a JSON file for automatic cookie loading at session start and saving at session end.

storage · RemoteFileStorage

Attach a file storage instance to the session for file operations.

perception_type · string · default: "fast"

Default perception type for observations: "fast" (simple) or "deep" (LLM-powered).

raise_on_failure · boolean · default: false

Raise exceptions when action execution fails instead of returning error results.

Session Response

When you start a session, you get access to these properties and methods:

session_response.py

from notte_sdk import NotteClient

client = NotteClient()

session = client.Session()
session.start()

# Session properties
session_id = session.session_id  # Unique identifier
cdp_url = session.cdp_url()  # Chrome DevTools Protocol URL
page = session.page  # Playwright page object

# Session status
status = session.status()  # Get current status

# Viewing
session.viewer()  # Open live viewer in browser
session.viewer_cdp()  # Open CDP debugger
session.viewer_notebook()  # Display in Jupyter notebook

# Cookies
cookies = session.get_cookies()
session.set_cookies(cookies=cookies)

session.stop()

# Replay
replay = session.replay()  # Get replay after session ends
replay.download("session.mp4")

Headless Mode

Control whether to run the browser visibly or in the background:

Python

from notte_sdk import NotteClient

client = NotteClient()

# Headless mode (no viewer)
with client.Session(headless=True) as session:
    page = session.page
    page.goto("https://example.com")

# Non-headless (opens live viewer automatically)
with client.Session(headless=False) as session:
    page = session.page
    page.goto("https://example.com")
    # Viewer opens automatically in your browser

When headless=False, a live viewer automatically opens in your browser so you can watch the automation in real-time.

Proxies

Route sessions through residential proxies for geo-targeting and enhanced stealth:

proxies_simple.py

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(proxies=True) as session:
    page = session.page
    page.goto("https://example.com")

See the Proxies Guide for country-specific proxies, custom proxies, and troubleshooting.

Captcha Solving

Automatically detect and solve captchas during automation:

Python

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(
    solve_captchas=True,
) as session:
    page = session.page
    page.goto("https://www.google.com/recaptcha/api2/demo")
    # Captchas are automatically solved

See the Captcha Solving guide for more details.

Session Timeout

Configure how long sessions stay active:

Python

from notte_sdk import NotteClient

client = NotteClient()

# Session closes after 10 minutes of inactivity
with client.Session(timeout_minutes=10) as session:
    page = session.page
    page.goto("https://example.com")

The timeout range is 1-30 minutes. Sessions automatically close when the timeout is reached.

Custom Viewport Size

Set custom screen dimensions for specific testing scenarios:

Python

from notte_sdk import NotteClient

client = NotteClient()

# 4K resolution
with client.Session(
    viewport_width=3840,
    viewport_height=2160
) as session:
    page = session.page
    page.goto("https://example.com")

Cookie Management

Automatically load and save cookies across sessions using the cookie_file parameter:

cookie_file.py

from notte_sdk import NotteClient

client = NotteClient()

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

See the Cookies Guide for manual cookie management and best practices.

External Providers (CDP)

Use Notte with external browser providers like Kernel.sh:

Python

from notte_sdk import NotteClient
from kernel import Kernel

client = NotteClient()
kernel = Kernel()

# Create browser on Kernel
kernel_browser = kernel.browsers.create()

# Connect Notte to Kernel's browser
with client.Session(cdp_url=kernel_browser.cdp_ws_url) as session:
    page = session.page
    page.goto("https://example.com")

See the Kernel.sh Integration guide for complete setup instructions.

Next Steps

Recordings

Watch recorded sessions and debug issues

Proxies

Configure proxies and anti-detection features

Live View

Watch sessions in real-time

Cookies

Persist authentication across sessions