Installation

Integrate Stagehand into an existing project.

Install Stagehand in your current app with the TypeScript SDK.

We recommend using the Node.js runtime environment to run Stagehand scripts.

Bun is now supported as long as you do not integrate Stagehand with Playwright. Playwright is not compatible with Bun.

TypeScript

Install dependencies

npm

npm install @browserbasehq/stagehand

pnpm add @browserbasehq/stagehand

yarn add @browserbasehq/stagehand

bun add @browserbasehq/stagehand

If you plan to run locally, you need to have Chrome installed on your machine. For cloud browser sessions, skip this.

Configure environment

Set environment variables (or a .env via your framework):

Bash

OPENAI_API_KEY=your_api_key
BROWSERBASE_API_KEY=your_api_key

Stagehand does not auto-load .env files.

If you use a .env file, install and initialize dotenv in your own app code:

npm install dotenv

import dotenv from "dotenv";
dotenv.config({ path: ".env" });

Use in your codebase

Add Stagehand where you need browser automation.

import dotenv from "dotenv";
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

dotenv.config({ path: ".env" });  // if needed

async function main() {
  const stagehand = new Stagehand({
    env: "BROWSERBASE"
  });

  await stagehand.init();
  const page = stagehand.context.pages()[0];

  await page.goto("https://example.com");

  // Act on the page
  await stagehand.act("Click the learn more button");

  // Extract structured data
  const description = await stagehand.extract("extract the description", z.string());

  console.log(description);
  await stagehand.close();
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Other Languages

For Python and other language SDKs, use the language selector in the top left corner of the sidebar to view the SDK documentation for your language.

Next steps

Configuration

Environment, Browserbase vs Local, logging, timeouts, LLM customization

Act

Perform precise actions with natural language

Extract

Typed data extraction with Zod schemas

Observe

Discover elements and suggested actions