Session Configurations

AI agent instructions

Read the Notte skill and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

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:

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

import { NotteClient, type SessionResponse } from 'notte-sdk';

const client = new NotteClient();
let status: SessionResponse | undefined;
let title: string | undefined;

const session = client.Session();
await session.use(async () => {
  status = await session.status();
  if (status.status !== 'active') throw new Error('Session is not active');
  const page = await session.page();
  await page.goto('https://example.com');
  title = await page.title();
  console.log(`Page title: ${title}`);
});
// Automatically stopped here.

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:

with client.Session(
    advanced_stealth=False,
    solve_captchas=True,
    proxies=True,
    viewport_width=1920,
    viewport_height=1080,
    idle_timeout_minutes=10,
) as session:
    page = session.page
    page.goto("https://example.com")

import { NotteClient, type SessionResponse } from 'notte-sdk';

const client = new NotteClient();
let status: SessionResponse | undefined;
let title: string | undefined;
let viewport: { width: number; height: number } | undefined;

const session = client.Session({
  idle_timeout_minutes: 10,
  advanced_stealth: false,
  solve_captchas: true,
  proxies: true,
  viewport_width: 1920,
  viewport_height: 1080,
});
await session.use(async () => {
  status = await session.status();
  if (status.status !== 'active') throw new Error('Session is not active');
  const page = await session.page();
  await page.goto('https://example.com');
  title = await page.title();
  console.log(`Page title: ${title}`);
  viewport = await page.evaluate(() => ({
    width: window.innerWidth,
    height: window.innerHeight,
  }));
  console.log(viewport);
});
// Automatically stopped here.

Common Parameters

boolean

default:false

Enable Notte’s highest-fidelity browser environment for sites with sophisticated bot detection. Access is currently available to approved workspaces; contact hello@notte.cc to enable it.

boolean

default:true

Automatically detect and solve captchas (reCAPTCHA, hCaptcha, etc.). Set this option on the session request. The retired global solve_captchas TOML key is ignored with a warning.

boolean

default:true

Save the session replay. Set to false at creation to disable saved recordings, including the cursor track. Live View and browser controls remain available. This setting cannot be changed after creation.

boolean

default:true

Save browser session steps, raw CDP messages, network logs and session API request/response content. Set to false at creation to disable these saved logs. Usage and billing counters still apply. This setting cannot be changed after creation. It does not disable separately requested files, profiles, screenshots, or agent and function histories.

These options require an API that supports session capture controls. The options are independent: disabling recording does not disable logs, and disabling logs does not disable recording. Omitted options keep the server defaults.

boolean

default:true

Block ads and trackers in managed browsers using Basic filtering, without cosmetic filtering or injected scriptlets. To opt out, use client.Session(block_ads=False) in Python or client.Session({ block_ads: false }) in TypeScript. When omitted, the SDK leaves the setting to the API default. Explicit values require an API that supports block_ads. This setting does not configure local browsers or externally connected CDP browsers.

boolean | string | list[ProxySettings]

default:true

Residential proxies are enabled by default. Set to false to disable them or provide custom proxy configuration. See Proxy Configuration for details.

integer

default:3

Idle timeout in minutes (max: 30). The session closes after this long without any operation; each operation resets it. Cannot exceed max_duration_minutes. timeout_minutes is accepted as a legacy alias.

integer

default:15

Maximum session lifetime in minutes (max: 1440), regardless of activity.

integer

Browser viewport width in pixels (minimum 500). Set together with viewport_height. When neither is set, Notte picks a viewport around 1280x1080.

integer

Browser viewport height in pixels (minimum 500). Set together with viewport_width.

string

Viewport shape preset: "5:4" or "16:9". Notte fits the largest viewport of this shape in the available screen area. Cannot be combined with viewport_width/viewport_height.

Advanced Parameters

string

Custom user agent string for the browser session.

list[str]

Custom Chrome/Chromium launch arguments. Advanced use only.

string

Connect to an external browser session via Chrome DevTools Protocol URL (e.g., from Kernel.sh or other providers). Proxies, user_agent, chrome_args, and the viewport must be configured with the external provider, so leave them unset (proxies default to off when cdp_url is set).

dict[str, str]

Extra HTTP headers sent with every request.

SessionProfile

Browser profile to load, with persist=True to save state back on close. See Browser Profiles.

string

Vault whose credentials the session can use. See Vaults.

boolean

default:false

Sign requests with Web Bot Auth. See Cloudflare Web Bot Auth.

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

RemoteFileStorage

Attach a file storage instance to the session for file operations. Python creates session.storage automatically when this is omitted. In TypeScript, create client.FileStorage() and pass it here before using storage.

string

default:"fast"

Default perception type for observations: "fast" (simple) or "deep" (LLM-powered). "deep" is deprecated and will be removed on December 1, 2026; use "fast". See the observe migration guide.

boolean

default:true

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

Managed Auth

list[str]

Up to 10 Managed Auth connection IDs to verify and, when needed, log in inside the session. While login runs, the session status is authenticating.

boolean

default:true

SDK option. When true, starting the session waits until authentication is ready. When false, call session.wait_for_auth() before browser actions.

integer

default:0

Additional retries (0 to 2) for transient Managed Auth login failures.

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")

Advanced Stealth

Use Notte’s approval-gated browser environment for difficult sites:

from notte_sdk import NotteClient

client = NotteClient()

# Advanced Stealth requires approval for your workspace.
with client.Session(advanced_stealth=True, open_viewer=True) as session:
    page = session.page
    page.goto("https://example.com")

Use open_viewer=True independently when you want the live viewer to open as the session starts.

Proxies

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

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

import { NotteClient, type SessionResponse } from 'notte-sdk';

const client = new NotteClient();
let status: SessionResponse | undefined;
let title: string | undefined;

const session = client.Session({ proxies: true });
await session.use(async () => {
  status = await session.status();
  if (status.status !== 'active') throw new Error('Session is not active');
  const page = await session.page();
  await page.goto('https://example.com');
  title = await page.title();
  console.log(`Page title: ${title}`);
});
// Automatically stopped here.

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

Captcha Solving

Automatically detect and solve captchas during automation:

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:

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

import { NotteClient, type SessionResponse } from 'notte-sdk';

const client = new NotteClient();
let status: SessionResponse | undefined;
let title: string | undefined;

const session = client.Session({ idle_timeout_minutes: 10 });
await session.use(async () => {
  status = await session.status();
  if (status.status !== 'active') throw new Error('Session is not active');
  const page = await session.page();
  await page.goto('https://example.com');
  title = await page.title();
  console.log(`Page title: ${title}`);
});
// Automatically stopped here.

The idle timeout ranges from 1 to 30 minutes and cannot exceed max_duration_minutes (default 15, max 1440). Sessions close when either limit is reached.

Custom Viewport Size

Set custom screen dimensions for specific testing scenarios:

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

import { NotteClient, type SessionResponse } from 'notte-sdk';

const client = new NotteClient();
let status: SessionResponse | undefined;
let title: string | undefined;
let viewport: { width: number; height: number } | undefined;

const session = client.Session({
  viewport_width: 3840,
  viewport_height: 2160,
});
await session.use(async () => {
  status = await session.status();
  if (status.status !== 'active') throw new Error('Session is not active');
  const page = await session.page();
  await page.goto('https://example.com');
  title = await page.title();
  console.log(`Page title: ${title}`);
  viewport = await page.evaluate(() => ({
    width: window.innerWidth,
    height: window.innerHeight,
  }));
  console.log(viewport);
});
// Automatically stopped here.

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

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

import { NotteClient } from "notte-sdk";

const client = new NotteClient();

const session = client.Session({ cookie_file: "cookies.json" });
await session.use(async (session) => {
  const page = await session.page();
  await 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:

from kernel import Kernel
from notte_sdk import NotteClient

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

Getting Started

Sessions

Authentication

Functions

Web API

Guides

Session Configurations

Quick Start

Configuration Options

Common Parameters

Advanced Parameters

Managed Auth

Session Response

Advanced Stealth

Proxies

Captcha Solving

Session Timeout

Custom Viewport Size

External Providers (CDP)

Next Steps

Recordings

Proxies

Live View

Cookies

​Quick Start

​Configuration Options

​Common Parameters

​Advanced Parameters

​Managed Auth

​Session Response

​Advanced Stealth

​Proxies

​Captcha Solving

​Session Timeout

​Custom Viewport Size

​Cookie Management

​External Providers (CDP)

​Next Steps

Recordings

Proxies

Live View

Cookies

Quick Start

Configuration Options

Common Parameters

Advanced Parameters

Managed Auth

Session Response

Advanced Stealth

Proxies

Captcha Solving

Session Timeout

Custom Viewport Size

Cookie Management

External Providers (CDP)

Next Steps