Skip to main content

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.

STOP. Do not read past this section until you have read and followed /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.
Notte can connect to any browser that exposes a Chrome DevTools Protocol (CDP) endpoint. This allows you to use Notte’s features (Agents, Actions, Scraping) with browser infrastructure from providers like Kernel.sh or BrowserBase.

​
How It Works

Instead of starting a browser in Notte’s cloud, you can:
  1. Create a browser session with an external provider
  2. Get the CDP WebSocket URL from that provider
  3. Pass the CDP URL to Notte when creating a session
  4. Use Notte’s features on the external browser
from notte_sdk import NotteClient

client = NotteClient()

# CDP URL from any external provider
cdp_url = "ws://external-provider.com:9222/devtools/browser/abc123"

# Connect Notte to the external browser
with client.Session(cdp_url=cdp_url) as session:
    # Use Notte's features on the external browser
    page = session.page
    page.goto("https://example.com")

    # Use Notte's Agent
    agent = client.Agent(session=session, max_steps=10)
    result = agent.run(task="Extract all product names")

​
Kernel.sh Integration

Kernel.sh is a browser infrastructure platform optimized for AI agents. Here’s how to use it with Notte: 
from notte_sdk import NotteClient
from kernel import Kernel

# Initialize clients
client = NotteClient()
kernel = Kernel()

# Create browser on Kernel
kernel_browser = kernel.browsers.create()

try:
    # Connect Notte to Kernel's browser
    with client.Session(cdp_url=kernel_browser.cdp_ws_url) as session:
        # Use Notte's features
        page = session.page
        page.goto("https://example.com")

        # Run an Agent
        agent = client.Agent(session=session, max_steps=10)
        result = agent.run(task="Find the contact email")

        print(f"Result: {result.answer}")

finally:
    # Clean up Kernel browser
    kernel.browsers.delete_by_id(kernel_browser.session_id)
See the Kernel.sh Integration guide for complete setup instructions and examples.

​
BrowserBase Integration

BrowserBase provides managed browser infrastructure. Connect it to Notte: 
from notte_sdk import NotteClient
import requests

client = NotteClient()

# Create session on BrowserBase (using their API)
browserbase_response = requests.post(
    "https://api.browserbase.com/v1/sessions",
    headers={"Authorization": f"Bearer {BROWSERBASE_API_KEY}"},
    json={"projectId": "your-project-id"}
)

session_data = browserbase_response.json()
cdp_url = session_data["cdpUrl"]

try:
    # Connect Notte to BrowserBase
    with client.Session(cdp_url=cdp_url) as session:
        page = session.page
        page.goto("https://example.com")

        # Use Notte's scraping
        result = session.scrape(
            instruction="Get all article titles",
            schema={"titles": ["string"]}
        )

        print(result)

finally:
    # Clean up BrowserBase session
    requests.delete(
        f"https://api.browserbase.com/v1/sessions/{session_data['id']}",
        headers={"Authorization": f"Bearer {BROWSERBASE_API_KEY}"}
    )

​
Benefits of External Providers

​
When to Use External Providers

Use external browser providers when you need:
  1. Specialized Infrastructure: Provider-specific optimizations or features
  2. Existing Setup: You already use a browser provider and want to add Notte’s features
  3. Compliance: Browsers must run in specific regions or under specific conditions
  4. Custom Configuration: Complex browser setups or extensions
  5. Cost Optimization: Leverage existing browser infrastructure contracts

​
When to Use Notte’s Browsers

Use Notte’s built-in browsers when you want:
  1. Simplicity: One-line session creation without managing external services
  2. Built-in Features: Anti-detection, captcha solving, proxies included
  3. Integrated Management: Session replay, cookie management, file storage
  4. Fast Setup: No additional configuration or API keys needed

​
What Notte Adds to External Browsers

When you connect Notte to an external browser, you get:

AI Agents

Use Notte’s Agent to automate complex tasks with natural language

Smart Actions

Execute high-level actions with automatic element detection

Structured Scraping

Extract data into structured formats with AI-powered scraping

Observation API

Get AI-powered page understanding and element analysis

​
Complete Example: Multi-Provider Setup

Run the same automation across different providers: 
from notte_sdk import NotteClient
from kernel import Kernel
from typing import Literal

client = NotteClient()

def run_automation(provider: Literal["notte", "kernel"], task: str):
    """Run automation on different browser providers"""

    if provider == "notte":
        # Use Notte's browser
        with client.Session() as session:
            agent = client.Agent(session=session)
            result = agent.run(task=task)
            return result

    elif provider == "kernel":
        # Use Kernel's browser
        kernel = Kernel()
        kernel_browser = kernel.browsers.create()

        try:
            with client.Session(cdp_url=kernel_browser.cdp_ws_url) as session:
                agent = client.Agent(session=session)
                result = agent.run(task=task)
                return result
        finally:
            kernel.browsers.delete_by_id(kernel_browser.session_id)

# Run on Notte's infrastructure
result1 = run_automation("notte", "Get the latest news from example.com")
print(f"Notte result: {result1.answer}")

# Run on Kernel's infrastructure
result2 = run_automation("kernel", "Get the latest news from example.com")
print(f"Kernel result: {result2.answer}")

​
Supported CDP Features

When using external browsers, Notte supports: ✅ Supported:
  • Page navigation and interaction via Playwright
  • Agent-based automation
  • Structured scraping with scrape()
  • Action execution with execute()
  • Page observation with observe()
  • Screenshot capture
  • JavaScript execution
  • Cookie management
  • Session replay recording
  • Live viewer
❌ Not Available:
  • Notte’s built-in anti-detection (use provider’s features instead)
  • Notte’s captcha solving (use provider’s features instead)
  • Notte’s proxy management (use provider’s proxies)

​
Troubleshooting

​
CDP Connection Failures

If connection fails, verify:
  1. URL Format: Ensure the CDP URL is correct (ws:// or wss:// prefix)
  2. Network Access: Check firewalls and network policies
  3. Browser Availability: Verify the browser is running and accessible
  4. Timeout: Increase session timeout for slow connections
# Add timeout and error handling
try:
    with client.Session(
        cdp_url=cdp_url,
        timeout_minutes=15  # Longer timeout
    ) as session:
        page = session.page
        page.goto("https://example.com")
except Exception as e:
    print(f"CDP connection failed: {e}")
    # Handle error or retry

​
Browser State Issues

When using external browsers:
  1. Start Fresh: Create new browser instances for each session
  2. Clean State: Clear cookies and cache between runs
  3. Session Cleanup: Always close/delete external browser sessions
  4. Resource Limits: Monitor memory and CPU usage

​
Authentication

Some providers require authentication in the CDP URL:
external_cdp_auth.py
from notte_sdk import NotteClient

client = NotteClient()

# CDP URL with authentication
cdp_url = "wss://user:password@provider.com:9222/devtools/browser/abc123"

with client.Session(cdp_url=cdp_url) as session:
    # Your automation
    pass

​
Provider Comparison

FeatureNotte Built-inKernel.sh + NotteBrowserBase + Notte
Setup ComplexitySimpleSimpleMedium
Anti-detection✅ Built-in✅ Built-in✅ Built-in
Captcha Solving✅ Optional❌❌
Residential Proxies✅ Optional✅✅
Session Replay✅ Yes✅ Via Notte✅ Via Notte
Live Viewer✅ Yes✅ Yes✅ Yes
PricingPer sessionPer sessionPer session

​
Best Practices

​
1. Clean Up Resources

Always clean up external browser sessions:
external_cleanup.py
        pass


provider = Provider()
client = NotteClient()

try:
    # Create external browser
    external_browser = provider.create()

    # Use with Notte
    with client.Session(cdp_url=external_browser.cdp_url) as session:
        # Your automation

​
2. Handle Errors Gracefully

CDP connections can fail. Always use try-except:
external_error_handling.py
from notte_sdk import NotteClient

client = NotteClient()

cdp_url = "wss://provider.com:9222/devtools/browser/abc123"

try:
    with client.Session(cdp_url=cdp_url) as session:
        # Your automation
        pass
except Exception as e:
    print(f"Automation failed: {e}")
    # Implement retry logic or fallback

​
3. Choose the Right Provider

  • High Volume: Use managed providers (Kernel, BrowserBase)
  • Simplicity: Use Notte’s built-in browsers
  • Existing Infrastructure: Connect to your current provider setup

​
4. Monitor Costs

External providers typically charge per session or minute. Monitor usage:
external_monitor_costs.py
import time

from notte_sdk import NotteClient

client = NotteClient()

cdp_url = "wss://provider.com:9222/devtools/browser/abc123"

start = time.time()

with client.Session(cdp_url=cdp_url) as session:
    # Your automation
    pass

duration = time.time() - start
print(f"Session duration: {duration:.2f} seconds")

​
Next Steps

Kernel.sh Integration

Complete Kernel.sh integration guide

Session Configuration

Learn about session configuration options

Connect with Playwright

Use Playwright directly with sessions

Session Lifecycle

Manage session states