Sessions

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.

List, create, and operate on browser sessions.

`notte sessions code`

Get Python script for session steps

Flag	Description
`--session-id <string>`	Session ID (uses current session if not specified)

`notte sessions cookies`

Get all cookies for the session

Flag	Description
`--session-id <string>`	Session ID (uses current session if not specified)

`notte sessions cookies-set`

Set cookies from a JSON file

Flag	Description
`--file <string>`	JSON file containing cookies array (required)
`--session-id <string>`	Session ID (uses current session if not specified)

`notte sessions list`

List active sessions

Flag	Description
`--all`, `-a`	Include stopped sessions
`--page <int>`	Page number (1-indexed)
`--page-size <int>`	Number of items per page

`notte sessions network`

Get network logs for the session

Flag	Description
`--path <string>`	Output directory for downloaded files (defaults to temp directory)
`--session-id <string>`	Session ID (uses current session if not specified)
`--urls-only`	Only show download URLs without downloading

`notte sessions offset`

Get session offset info

Flag	Description
`--session-id <string>`	Session ID (uses current session if not specified)

`notte sessions replay`

Download the replay video (MP4) for a session. Examples:

notte sessions replay                       # saves to temp directory
notte sessions replay --path replay.mp4    # saves to specified path

Flag	Description
`--path <string>`	Output path for the replay video (defaults to temp directory)
`--session-id <string>`	Session ID (uses current session if not specified)

`notte sessions save-profile`

Save the running session’s browser state (cookies, localStorage, sessionStorage) into a browser profile. The session keeps running. Pass --profile-id to overwrite an existing profile, or --name to create a new one. With neither, the state is saved into the profile the session was started with.

Flag	Description
`--name <string>`	Create a new profile with this name and save into it
`--profile-id <string>`	Existing profile to overwrite
`--session-id <string>`	Session ID (uses current session if not specified)

`notte sessions start`

Start a new browser session

Flag	Description
`--advanced-stealth`	Enable Notte’s highest-fidelity browser environment for sites with sophisticated bot detection. Available to approved workspaces. (API default: false)
`--aspect-ratio <string>`	Viewport shape preset. When set, the backend fits the largest rectangle of this aspect ratio inside the sampled available screen area. Cannot be combined with explicit viewport_width/viewport_height.
`--auth-ids <strings>`	Managed Auth connection IDs to verify and, when necessary, authenticate inside this session. Initial verification runs before returning; when login is needed, the session returns as authenticating. Poll /sessions/{id}/auth for readiness. (repeatable)
`--auth-retry <int>`	auth-retry (API default: 0)
`--block-ads`	Block ads and trackers in managed browsers using Basic filtering. Set false to disable. Does not configure externally supplied CDP browsers. (API default: true)
`--browser-type <string>`	The browser type to use. Supported values are chromium and chrome. chrome-nightly and chrome-turbo are legacy aliases for chrome. (API default: chromium) (chromium, chrome, chrome-nightly, chrome-turbo)
`--cdp-url <string>`	The CDP URL of another remote session provider.
`--chrome-args <strings>`	Overwrite the chrome instance arguments (repeatable)
`--demonstrate`	Whether to enable the Notte recorder extension for this session. The extension is installed but remains inactive when this is false. (API default: false)
`--extra-http-headers <string>`	Extra HTTP headers as JSON (e.g. ’{“Authorization”: “Bearer xxx”}‘)
`--idle-timeout-minutes <int>`	Idle timeout in minutes. Session closes after this period of inactivity (resets on each operation). (API default: 3)
`--max-duration-minutes <int>`	Maximum session lifetime in minutes (absolute maximum, not affected by activity). (API default: 15)
`--no-solve-captchas`	Do not attempt to solve captchas automatically
`--profile-id <string>`	Profile ID to use for this session
`--profile-persist`	Whether to save browser state to profile on session close (API default: false)
`--proxy`	Use default proxies
`--proxy-country <string>`	Proxy country code (e.g. us, gb, fr). Selects a proxy on its own; do not combine with `--proxy`
`--proxy-external-password <string>`	External proxy password
`--proxy-external-server <string>`	External proxy server URL (e.g. http://proxy:8080). Enables external proxy
`--proxy-external-username <string>`	External proxy username
`--proxy-tailnet-client-id <string>`	Tailnet OAuth client ID. Enables Tailscale proxy
`--proxy-tailnet-client-secret <string>`	Tailnet OAuth client secret
`--screenshot-type <string>`	The type of screenshot to use for the session. (API default: last_action) (raw, full, last_action)
`--solve-captchas`	Whether to try to automatically solve captchas (API default: true)
`--tunnel <notte tunnel up>`	Route public traffic through a saved tunnel (see notte tunnel up)
`--user-agent <string>`	The user agent to use for the session
`--vault-id <string>`	The vault to use for the session
`--viewport-height <int>`	Viewport height in pixels (minimum 500). Set together with viewport_width.
`--viewport-width <int>`	Viewport width in pixels (minimum 500). Set together with viewport_height.
`--wait-for-authentication`	SDK waiting preference. The API always verifies inline and returns authenticating when background login is needed; SDKs implement waiting through readiness polling. (API default: true)
`--web-bot-auth`	Whether to use web bot authentication. (API default: false)

`notte sessions status`

Get session status

Flag	Description
`--auth`	Show managed authentication readiness and operations
`--session-id <string>`	Session ID (uses current session if not specified)

`notte sessions stop`

Stop the session

Flag	Description
`--session-id <string>`	Session ID (uses current session if not specified)

`notte sessions viewer`

Open session viewer in browser

Flag	Description
`--session-id <string>`	Session ID (uses current session if not specified)

`notte sessions workflow-code`

Export session steps as code

Flag	Description
`--session-id <string>`	Session ID (uses current session if not specified)

Getting Started

Commands

`notte sessions code`

`notte sessions cookies`

`notte sessions cookies-set`

`notte sessions list`

`notte sessions network`

`notte sessions offset`

`notte sessions replay`

`notte sessions save-profile`

`notte sessions start`

`notte sessions status`

`notte sessions stop`

`notte sessions viewer`

`notte sessions workflow-code`

​notte sessions code

​notte sessions cookies

​notte sessions cookies-set

​notte sessions list

​notte sessions network

​notte sessions offset

​notte sessions replay

​notte sessions save-profile

​notte sessions start

​notte sessions status

​notte sessions stop

​notte sessions viewer

​notte sessions workflow-code

`notte sessions code`

`notte sessions cookies`

`notte sessions cookies-set`

`notte sessions list`

`notte sessions network`

`notte sessions offset`

`notte sessions replay`

`notte sessions save-profile`

`notte sessions start`

`notte sessions status`

`notte sessions stop`

`notte sessions viewer`

`notte sessions workflow-code`