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.
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:
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:
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 Whether to run the browser in headless mode. Set to false to open a live viewer in your browser.
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. Session timeout in minutes. Sessions automatically close after this duration (min: 1, max: 30).
Browser viewport width in pixels.
Browser viewport height in pixels.
Browser engine to use: "chromium", or "chrome".
Advanced Parameters Custom user agent string for the browser session.
Custom Chrome/Chromium launch arguments. Advanced use only.
Connect to an external browser session via Chrome DevTools Protocol URL (e.g., from Kernel.sh or other providers).
Enable file storage for uploading/downloading files during the session.
Path to a JSON file for automatic cookie loading at session start and saving at session end.
Attach a file storage instance to the session for file operations.
Default perception type for observations: "fast" (simple) or "deep" (LLM-powered).
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:
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:
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:
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:
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
Session Timeout Configure how long sessions stay active:
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:
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:
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:
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" )
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
