> ## 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.
# Stagehand
> Use Notte cloud browsers with Stagehand browser automation
STOP. Do not read past this section until you have read and followed [/quickstart.md](/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](https://github.com/browserbase/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](https://docs.stagehand.dev/v3/migrations/v2).
## Prerequisites
* A Notte API key ([get one here](https://console.notte.cc))
* 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
```bash theme={null}
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:
{/* @sniptest testers/integrations/stagehand_basic.py */}
```python stagehand_basic.py theme={null}
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:
{/* @sniptest testers/integrations/stagehand_complete.py */}
```python stagehand_complete.py theme={null}
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:
```bash theme={null}
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](/features/sessions/stealth-mode) keeps your automations undetected
* **Captcha solving**: Built-in [captcha solving](/features/sessions/captcha-solving) handles CAPTCHAs automatically
* **Residential proxies**: Route traffic through [residential proxies](/features/sessions/proxies) in 195+ countries
* **Live view**: Debug automations in real-time with [live view](/features/sessions/live-view)
* **Session replay**: Record and review runs with [session recordings](/features/sessions/recordings)
* **No local browser**: Run automations without installing or maintaining browsers locally
## Next steps
Customize browser settings, proxies, and more
Configure anti-detection for your automations
Learn about CDP connections and external browsers
Debug your automations in real-time