Installation

Integrate Stagehand into an existing project.

Install Stagehand in your current app with the TypeScript or Python SDK.

For TypeScript/Node.js: We highly recommend using the Node.js runtime environment to run Stagehand scripts, as opposed to newer alternatives like Deno or Bun.

Bun does not support Stagehand since it doesn’t support Playwright.

For Python: We require Python 3.9+ and recommend using uv to manage your virtual environment.

TypeScript

Install dependencies

npm

npm install @browserbasehq/stagehand playwright zod

If you plan to run locally, install browsers once: npx playwright install. 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
BROWSERBASE_PROJECT_ID=your_project_id

Use in your codebase

Add Stagehand where you need browser automation.

TypeScript

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

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

  await stagehand.init();
  const page = stagehand.page;

  await page.goto("https://example.com");
  
  // Act on the page
  await page.act("Click the sign in button");
  
  // Extract structured data
  const { title } = await page.extract({
    instruction: "extract the page title",
    schema: z.object({
      title: z.string(),
    }),
  });

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

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

Python

Add dependencies

uv

uv add stagehand

Configure environment

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

Bash

MODEL_API_KEY=your_api_key
BROWSERBASE_API_KEY=your_api_key
BROWSERBASE_PROJECT_ID=your_project_id

Use in your codebase

Python

import os
import asyncio
from stagehand import Stagehand

async def main():
    stagehand = Stagehand(
        env="BROWSERBASE",
        model_api_key=os.getenv("MODEL_API_KEY")
    )
    await stagehand.init()
    page = stagehand.page
    
    await page.goto("https://example.com")
    
    # Act on the page
    await page.act("Click the sign in button")
    
    # Extract structured data
    result = await page.extract({
        "instruction": "extract the page title",
        "schema": {
            "title": {
                "type": "string"
            }
        }
    })
    
    print(result["title"])
    await stagehand.close()

if __name__ == "__main__":
    asyncio.run(main())

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