Skip to main content

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:

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

2. Install dependencies​

npm install @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​