Stagehand Integration

Stagehand is an open-source AI browser automation framework that lets you control web browsers using natural language and code. By connecting Stagehand to Browserless, you get reliable cloud-hosted browsers without managing Chrome infrastructure yourself, complete with stealth mode, residential proxies, and enterprise-grade reliability.

Prerequisites

• Node.js 18 or later
• Browserless API token (available in your account dashboard)
• An LLM API key (Anthropic, OpenAI, etc.)

Step-by-Step Setup

1. Get your API keys

   Go to your Browserless account dashboard and copy your API token.

   Then set your environment variables:

   .env file

   BROWSERLESS_API_KEY=your-browserless-token
   ANTHROPIC_API_KEY=your-anthropic-key

   Command line

   export BROWSERLESS_API_KEY=your-browserless-token
   export ANTHROPIC_API_KEY=your-anthropic-key

2. Install dependencies

   npm

   npm install @browserbasehq/stagehand zod

   pnpm

   pnpm add @browserbasehq/stagehand zod

3. Connect to Browserless

   Pass the Browserless WebSocket URL directly to Stagehand's cdpUrl config:

   import { Stagehand } from "@browserbasehq/stagehand";
   
   const stagehand = new Stagehand({
     env: "LOCAL",
     localBrowserLaunchOptions: {
       cdpUrl: `wss://production-sfo.browserless.io?token=${process.env.BROWSERLESS_API_KEY}`,
     },
     model: "anthropic/claude-sonnet-4-5",
   });
   
   await stagehand.init();

4. Use your Stagehand automation

   Use Stagehand's page methods with the Browserless-powered browser:

   import { Stagehand } from "@browserbasehq/stagehand";
   import { z } from "zod";
   
   const stagehand = new Stagehand({
     env: "LOCAL",
     localBrowserLaunchOptions: {
       cdpUrl: `wss://production-sfo.browserless.io?token=${process.env.BROWSERLESS_API_KEY}`,
     },
     model: "anthropic/claude-sonnet-4-5",
   });
   
   await stagehand.init();
   
   const page = stagehand.context.pages()[0];
   
   // Navigate to Browserless
   await page.goto("https://www.browserless.io");
   
   // act() - Click on Documentation
   await stagehand.act("click on the Docs link in the navigation");
   
   // extract() - Get documentation sections
   const docs = await stagehand.extract(
     "extract the main documentation categories or sections",
     z.object({
       sections: z.array(z.object({
         title: z.string(),
         description: z.string().optional(),
       })),
     })
   );
   console.log("Documentation sections:", docs.sections);
   
   // Clean up when done
   await stagehand.close();

Why use Browserless with Stagehand

• Stealth mode: bypass bot detection by adding /stealth to the endpoint URL
• Residential proxies: route traffic through real residential IPs to avoid blocks
• Global regions: choose from US West (San Francisco), Europe (London), or Europe (Amsterdam) endpoints for lower latency
• No infrastructure: skip managing Chrome installations, updates, or scaling
• Parallel sessions: run multiple browser sessions simultaneously
• Enterprise reliability: 99.9% uptime SLA with automatic failover

Resources

• Stagehand Documentation
• Browserless Connection Options
• Stealth Mode
• Proxy Configuration
• Stagehand GitHub Repository

FAQ & Troubleshooting

How do I connect Stagehand to Browserless?

Set localBrowserLaunchOptions.cdpUrl to your Browserless WebSocket URL (wss://production-sfo.browserless.io?token=YOUR_TOKEN) when creating the Stagehand instance, as shown in step 3 above.

Which LLM models can I use with Stagehand?

Stagehand accepts any model string in provider/model format, such as anthropic/claude-sonnet-4-5 or openai/gpt-4o. Set the matching API key as an environment variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) for whichever provider you use.

Stagehand's act() or extract() can't find the right element

Use the /stealth endpoint instead of the default one in your cdpUrl if the site is blocking automated browsers. See stealth mode for configuration details. If the page loads dynamic content, make sure you await navigation and any async rendering before calling act() or extract().

Next steps

Browser Agent

a managed alternative that skips the setup and model wiring

AI integrations overview

all supported AI frameworks and tools