Quickstart

You can get started with Stagehand in just 1 minute! Choose your preferred language below.

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

Before you begin, you’ll need to install Node.js and NPM. We highly recommend using nvm to manage your Node.js versions, and running on Node version 20+.

Create a new project

You can use npx to create a new project. You should have npx included with npm, the default package manager for Node.js.

npm
pnpm
yarn

npx create-browser-app

pnpm create browser-app

yarn create browser-app

To use our Contexts with Stagehand, run:

npm
pnpm
yarn

npx create-browser-app --example persist-context

pnpm create browser-app --example persist-context

yarn create browser-app --example persist-context

You can easily deploy Stagehand scripts to Vercel in one line! Simply run:

npm
pnpm
yarn

npx create-browser-app --example deploy-vercel
npx vercel deploy

pnpm create browser-app --example deploy-vercel

yarn create browser-app --example deploy-vercel

We also have an example using CUA agents, where we put OpenAI Operator against Anthropic’s Claude Computer Use in a heated game of chess. It’s just ten lines of Stagehand code, try it with:

npm
pnpm
yarn

npx create-browser-app --example chess

pnpm create browser-app --example chess

yarn create browser-app --example chess

You can also use the version of Stagehand that’s on main but not released yet. This will have the bleeding edge features, but they may not be fully prod-ready yet. To test this version, try:

npm
pnpm
yarn

npx create-browser-app --alpha

pnpm create browser-app --alpha

yarn create browser-app --alpha

It will ask you the following questions:

✔ What is the name of your project? my-app
✔ Would you like to start with a quickstart example? Yes
✔ Select AI model: Anthropic Claude 3.7 Sonnet
✔ Run locally or on Browserbase? Local
✔ Run browser in headless mode (hide Chromium popup)?  No

Install dependencies and run the script

npm
pnpm
yarn

cd my-app
npm install
npm run start

cd my-app
pnpm install
pnpm run start

cd my-app
yarn install
yarn start

Use the package manager of your choice to install the dependencies. We also have a postinstall script that will automatically install the Playwright browser with playwright install.

Adding Stagehand to an existing project:

Install Stagehand

npm install @browserbasehq/stagehand

Set up environment variables

Create a .env file or export environment variables:

export BROWSERBASE_API_KEY="your_browserbase_api_key"
export BROWSERBASE_PROJECT_ID="your_browserbase_project_id"
export OPENAI_API_KEY="your_openai_api_key"  # Configurable to other models

Create your first script

Create a file index.ts:

// index.ts
import { Stagehand, ConstructorParams } from "@browserbasehq/stagehand";
import dotenv from "dotenv";
import { z } from "zod";

dotenv.config();

export async function main() {
  const config: ConstructorParams = {
    env: "BROWSERBASE", // or "LOCAL"
    apiKey: process.env.BROWSERBASE_API_KEY,
    projectId: process.env.BROWSERBASE_PROJECT_ID,
    verbose: 1,
  };

  const stagehand = new Stagehand(config);

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

    await page.goto("https://docs.stagehand.dev/");
    await page.act("click the quickstart link");

    const result = await page.extract({
      instruction: "extract the main heading of the page",
      schema: z.object({
        heading: z.string(),
      }),
    });

    console.log(`Extracted: ${result.heading}`);
  } catch (error) {
    console.error(error);
  } finally {
    await stagehand.close();
  }
}

main();

Run the script

npx tsx index.ts

Before you begin, you’ll need Python 3.9+ installed. We recommend using uv to manage your virtual environment.

Install Stagehand Python

pip install stagehand

Set up environment variables

Create a .env file or export environment variables:

export BROWSERBASE_API_KEY="your_browserbase_api_key"
export BROWSERBASE_PROJECT_ID="your_browserbase_project_id"
export MODEL_API_KEY="your_model_api_key"  # OpenAI, Anthropic, etc.

Create your first script

Create a file main.py:

import asyncio
import os
from stagehand import Stagehand, StagehandConfig
from dotenv import load_dotenv

load_dotenv()

async def main():
    config = StagehandConfig(
        env="BROWSERBASE",
        api_key=os.getenv("BROWSERBASE_API_KEY"),
        project_id=os.getenv("BROWSERBASE_PROJECT_ID"),
        model_name="gpt-4o",
        model_api_key=os.getenv("MODEL_API_KEY")
    )
    
    stagehand = Stagehand(config)
    
    try:
        await stagehand.init()
        page = stagehand.page
        
        await page.goto("https://docs.stagehand.dev/")
        await page.act("click the quickstart link")
        
        result = await page.extract("extract the main heading of the page")
        
        print(f"Extracted: {result}")
        
    finally:
        await stagehand.close()

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

Run the script

python main.py

Next Steps

Check out the TypeScript repo

If you’re a TypeScript developer, you can check out the Stagehand TypeScript repo. PRs welcome!

Check out the Python repo

Stagehand now supports Python! The Python repo is brand new, so PRs are more than welcome!

Get Started

Concepts

Playbooks

Reference

Integrations

Adding Stagehand to an existing project:

Check out the TypeScript repo

Check out the Python repo

​Adding Stagehand to an existing project:

Check out the TypeScript repo

Check out the Python repo

Adding Stagehand to an existing project: