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

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

<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.md) 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.md) 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.md) 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.md) guide for complete setup instructions.
</Note>

## Next Steps

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

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

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

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