> ## 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.

# Session Configurations

> Learn how to create and configure Notte browser sessions

<Tip>
  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.
</Tip>

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:

<CodeGroup>
  ```python Python theme={null}
  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")
  ```
</CodeGroup>

Active sessions can be viewed and managed in the [Sessions](https://console.notte.cc/sessions) page in the console.

<Tip>
  Sessions are automatically stopped when exiting the context manager. Always use the `with` statement to ensure proper cleanup.
</Tip>

## Configuration Options

Customize your session with these options:

<CodeGroup>
  ```python Python theme={null}
  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")
  ```
</CodeGroup>

### Common Parameters

<ParamField path="headless" type="boolean" default={true}>
  Whether to run the browser in headless mode. Set to `false` to open a live viewer in your browser.
</ParamField>

<ParamField path="solve_captchas" type="boolean" default={false}>
  Automatically detect and solve captchas (reCAPTCHA, hCaptcha, etc.)
</ParamField>

<ParamField path="proxies" type="boolean | list[ProxySettings]" default={false}>
  Enable residential proxies. Set to `true` for default proxies or provide custom proxy configuration.
  See [Proxy Configuration](#proxies) for details.
</ParamField>

<ParamField path="timeout_minutes" type="integer" default={3}>
  Session timeout in minutes. Sessions automatically close after this duration (min: 1, max: 30).
</ParamField>

<ParamField path="viewport_width" type="integer" default={1280}>
  Browser viewport width in pixels.
</ParamField>

<ParamField path="viewport_height" type="integer" default={1080}>
  Browser viewport height in pixels.
</ParamField>

<ParamField path="browser_type" type="string" default={"chrome"}>
  Browser engine to use: `"chromium"`, or `"chrome"`.
</ParamField>

### Advanced Parameters

<ParamField path="user_agent" type="string">
  Custom user agent string for the browser session.
</ParamField>

<ParamField path="chrome_args" type="list[str]">
  Custom Chrome/Chromium launch arguments. Advanced use only.
</ParamField>

<ParamField path="cdp_url" type="string">
  Connect to an external browser session via Chrome DevTools Protocol URL (e.g., from Kernel.sh or other providers).
</ParamField>

<ParamField path="use_file_storage" type="boolean" default={false}>
  Enable file storage for uploading/downloading files during the session.
</ParamField>

<ParamField path="cookie_file" type="string | Path">
  Path to a JSON file for automatic cookie loading at session start and saving at session end.
</ParamField>

<ParamField path="storage" type="RemoteFileStorage">
  Attach a file storage instance to the session for file operations.
</ParamField>

<ParamField path="perception_type" type="string" default="fast">
  Default perception type for observations: `"fast"` (simple) or `"deep"` (LLM-powered).
</ParamField>

<ParamField path="raise_on_failure" type="boolean" default={false}>
  Raise exceptions when action execution fails instead of returning error results.
</ParamField>

## Session Response

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

{/* @sniptest testers/sessions/configuration/session_response.py */}

```python session_response.py theme={null}
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:

<CodeGroup>
  ```python Python theme={null}
  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
  ```
</CodeGroup>

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

## Proxies

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

{/* @sniptest testers/sessions/configuration/proxies_simple.py */}

```python proxies_simple.py theme={null}
from notte_sdk import NotteClient

client = NotteClient()

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

<Note>
  See the [Proxies Guide](/features/sessions/proxies) for country-specific proxies, custom proxies, and troubleshooting.
</Note>

## Captcha Solving

Automatically detect and solve captchas during automation:

<CodeGroup>
  ```python Python theme={null}
  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
  ```
</CodeGroup>

<Note>
  See the [Captcha Solving](/features/sessions/captcha-solving) guide for more details.
</Note>

## Session Timeout

Configure how long sessions stay active:

<CodeGroup>
  ```python Python theme={null}
  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")
  ```
</CodeGroup>

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:

<CodeGroup>
  ```python Python theme={null}
  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")
  ```
</CodeGroup>

## Cookie Management

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

{/* @sniptest testers/sessions/configuration/cookie_file.py */}

```python cookie_file.py theme={null}
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
```

<Note>
  See the [Cookies Guide](/features/sessions/cookies) for manual cookie management and best practices.
</Note>

## External Providers (CDP)

Use Notte with external browser providers like Kernel.sh:

<CodeGroup>
  ```python Python theme={null}
  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")
  ```
</CodeGroup>

<Note>
  See the [Kernel.sh Integration](/integrations/kernel) guide for complete setup instructions.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Recordings" icon="video" href="/features/sessions/recordings">
    Watch recorded sessions and debug issues
  </Card>

  <Card title="Proxies" icon="user-secret" href="/features/sessions/proxies">
    Configure proxies and anti-detection features
  </Card>

  <Card title="Live View" icon="eye" href="/features/sessions/live-view">
    Watch sessions in real-time
  </Card>

  <Card title="Cookies" icon="cookie-bite" href="/features/sessions/cookies">
    Persist authentication across sessions
  </Card>
</CardGroup>