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
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
// 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');
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
const observations = await stagehand.observe('What actions can I take on this page?');
With Session Options
const session = await client.browser.session.create({
country: 'US',
type: 'hosted',
windowSize: '1920x1080',
profile: { name: 'stagehand-session', persist: true },
});
Complex Workflows
// 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