Skip to main content
Stagehand is an AI-native browser automation framework that uses natural language to interact with web pages.

Installation

npm install @browserbasehq/stagehand @browsercash/sdk zod
CDP URL attachment requires Stagehand 2.0 or newer. In LOCAL mode, Stagehand also needs an API key for your chosen model provider.
DRIVER_API_KEY=your-driver-key
OPENAI_API_KEY=your-openai-key

Quick Start

TypeScript
import { Stagehand } from '@browserbasehq/stagehand';
import BrowsercashSDK from '@browsercash/sdk';
import { z } from 'zod';

async function run() {
  const client = new BrowsercashSDK({
    apiKey: process.env.DRIVER_API_KEY!,
    baseURL: "https://api.driver.dev",
  });

  // Create Driver session
  const session = await client.browser.session.create({ type: 'hosted' });

  // Initialize Stagehand with Driver CDP URL
  const stagehand = new Stagehand({
    env: 'LOCAL',
    model: 'openai/gpt-5',
    localBrowserLaunchOptions: {
      cdpUrl: session.cdpUrl,
    },
  });

  await stagehand.init();

  const page = stagehand.context.pages()[0] || await stagehand.context.newPage();
  await page.goto('https://example.com');

  // Extract data using natural language
  const data = await stagehand.extract(
    'Extract the page title and main heading',
    z.object({
      title: z.string(),
      heading: z.string(),
    })
  );

  console.log(data);

  // Cleanup
  await stagehand.close();
  await client.browser.session.stop({ sessionId: session.sessionId });
}

run().catch(console.error);

Key Features

Natural Language Actions

TypeScript
// Click elements
await stagehand.act('click the sign up button');

// Fill forms
await stagehand.act('enter "John Doe" in the name field');

// Navigate
await stagehand.act('scroll down to the pricing section');

Structured Data Extraction

TypeScript
const products = await stagehand.extract(
  'Extract all products with their prices',
  z.array(z.object({
    name: z.string(),
    price: z.number(),
    inStock: z.boolean(),
  }))
);

Observe Page State

TypeScript
const observations = await stagehand.observe('What actions can I take on this page?');

With Session Options

TypeScript
const session = await client.browser.session.create({
  country: 'US',
  type: 'hosted',
  windowSize: '1920x1080',
  profile: { name: 'stagehand-session', persist: true },
});

Complex Workflows

TypeScript
// Multi-step workflow with error handling
async function checkoutFlow(stagehand: Stagehand) {
  const page = stagehand.context.pages()[0] || await stagehand.context.newPage();
  await page.goto('https://shop.example.com');

  await stagehand.act('search for "laptop"');
  await stagehand.act('click on the first product');
  await stagehand.act('add to cart');
  await stagehand.act('go to checkout');

  const cartSummary = await stagehand.extract(
    'Extract the cart total and item count',
    z.object({
      total: z.string(),
      itemCount: z.number(),
    })
  );

  return cartSummary;
}

Why Stagehand + Driver?

  • AI-native — Use natural language instead of brittle selectors
  • Self-healing — Adapts to UI changes automatically
  • Hosted browsers — Run Stagehand on managed Chrome sessions
  • Scalable — No local browser management needed