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.

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