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.
Stagehand is an open source AI browser automation framework that lets you choose what to write in code vs. natural language. By integrating with Notte, you can run Stagehand automations on cloud-hosted browsers with built-in anti-detection, captcha solving, and residential proxies.
This guide is compatible with Stagehand v3. If you’re using an earlier version, refer to the Stagehand migration guide.

​
Prerequisites

  • A Notte API key (get one here)
  • An LLM API key (e.g., OpenAI)
  • Stagehand v3

​
Adding Notte to existing Stagehand implementations

If you already have a Stagehand v3 implementation, you can switch to using Notte’s cloud browsers by updating your browser configuration.

​
1. Install the SDKs

pip install notte-sdk stagehand

​
2. Connect Stagehand to a Notte browser

Create a Notte cloud browser session and pass its CDP URL to Stagehand:
stagehand_basic.py
import asyncio
import os

from notte_sdk import NotteClient
from stagehand import Stagehand


async def main():
    client = NotteClient()

    with client.Session() as session:
        # Connect Stagehand to Notte's cloud browser via CDP
        stagehand = Stagehand(
            env="LOCAL",
            local_browser_launch_options={
                "cdp_url": session.cdp_url(),
            },
            model_name="openai/gpt-4.1",
            model_api_key=os.environ.get("MODEL_API_KEY"),
        )
        await stagehand.init()

        page = stagehand.page
        await page.goto("https://example.com")
        await stagehand.act("Click on the 'More information...' link")

        await stagehand.close()


asyncio.run(main())
That’s it — Stagehand is now running on a Notte cloud browser with built-in stealth and anti-detection.

​
Complete example

A production-ready script using Stagehand’s observe, act, and extract on a Notte browser:
stagehand_complete.py
import asyncio
import os

from dotenv import load_dotenv
from notte_sdk import NotteClient
from stagehand import Stagehand

load_dotenv()


async def main():
    client = NotteClient()

    with client.Session() as session:
        stagehand = Stagehand(
            env="LOCAL",
            local_browser_launch_options={
                "cdp_url": session.cdp_url(),
            },
            model_name="openai/gpt-4.1",
            model_api_key=os.environ.get("MODEL_API_KEY"),
            verbose=1,
        )
        await stagehand.init()

        try:
            # Navigate to a webpage
            page = stagehand.page
            await page.goto("https://news.ycombinator.com")

            # Observe: find possible actions on the page
            observations = await stagehand.observe("find the top story link")
            print(f"Found {len(observations)} possible actions")

            # Act: click on the first result
            if observations:
                await stagehand.act(observations[0])

            # Extract: get structured data from the page
            result = await stagehand.extract(
                "extract the title and URL of this story",
                {
                    "type": "object",
                    "properties": {
                        "title": {"type": "string"},
                        "url": {"type": "string"},
                    },
                },
            )
            print(f"Extracted: {result}")

        finally:
            await stagehand.close()

    print("Done")


if __name__ == "__main__":
    asyncio.run(main())
Set the following environment variables in your .env file: 
NOTTE_API_KEY=your-notte-api-key
MODEL_API_KEY=your-openai-api-key

​
Benefits of using Notte with Stagehand

  • Anti-detection: Notte’s stealth mode keeps your automations undetected
  • Captcha solving: Built-in captcha solving handles CAPTCHAs automatically
  • Residential proxies: Route traffic through residential proxies in 195+ countries
  • Live view: Debug automations in real-time with live view
  • Session replay: Record and review runs with session recordings
  • No local browser: Run automations without installing or maintaining browsers locally

​
Next steps

Session Configuration

Customize browser settings, proxies, and more

Stealth Mode

Configure anti-detection for your automations

External Providers

Learn about CDP connections and external browsers

Live View

Debug your automations in real-time