Installation

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
Python

Install dependencies

npm install @browserbasehq/stagehand playwright zod

pnpm add @browserbasehq/stagehand playwright zod

yarn add @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):

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.

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);
});

Add dependencies

uv add stagehand

pip install stagehand

Configure environment

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

MODEL_API_KEY=your_api_key
BROWSERBASE_API_KEY=your_api_key
BROWSERBASE_PROJECT_ID=your_project_id

Use in your codebase

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

First Steps

The Basics

Configuration

Best Practices

Integrations

Reference

Install dependencies

Configure environment

Use in your codebase

Add dependencies

Configure environment

Use in your codebase

Next steps

Configuration

Act

Extract

Observe

​Install dependencies

​Configure environment

​Use in your codebase

​Add dependencies

​Configure environment

​Use in your codebase

​Next steps

Configuration

Act

Extract

Observe

Install dependencies

Configure environment

Use in your codebase

Add dependencies

Configure environment

Use in your codebase

Next steps