Skip to main content

​
Package Installation

Install Stagehand using your preferred package manager: 
npm install @browserbasehq/stagehand

​
System Requirements

Node.js Version

Requires Node.js ^20.19.0 or >=22.12.0

Package Manager

Supports npm, pnpm (9.15.0+), and yarn

TypeScript

TypeScript 5.8.3+ recommended for type safety

Browser

Chrome/Chromium required for local environment

​
Dependencies

Stagehand has the following peer dependencies: 
{
  "deepmerge": "^4.3.1",
  "zod": "^3.25.76 || ^4.2.0"
}
These will be automatically installed when you add Stagehand to your project.

​
Quick Start Installation

The fastest way to get started is with the project generator: 
npx create-browser-app
This command creates a new project with:
  • Stagehand pre-installed and configured
  • Example automation scripts
  • Environment variable templates
  • TypeScript support

​
Building from Source

For development or to use the latest features from the main branch:
1

Clone the Repository

git clone https://github.com/browserbase/stagehand.git
cd stagehand
2

Install Dependencies

pnpm install
The repository uses pnpm workspaces. Make sure you have pnpm installed: npm install -g pnpm
3

Build the Project

pnpm run build
This compiles both ESM and CommonJS versions of the library.
4

Run Example Scripts

pnpm run example
This runs the example script at ./examples/example.ts

​
Installing from a Branch

You can install Stagehand directly from a GitHub branch using gitpkg: In your project’s package.json: 
{
  "dependencies": {
    "@browserbasehq/stagehand": "https://gitpkg.now.sh/browserbase/stagehand/packages/core?<branchName>"
  }
}
Replace <branchName> with the branch you want to install from (e.g., main, develop, or a feature branch).

​
Environment Setup

After installation, configure your environment variables:

​
Option 1: Using Browserbase (Recommended)

For production environments, use Browserbase’s cloud browser infrastructure:
.env
# Browserbase credentials
BROWSERBASE_API_KEY=your_api_key_here
BROWSERBASE_PROJECT_ID=your_project_id_here

# AI Model (choose one)
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
Get your Browserbase API key and project ID from browserbase.com

​
Option 2: Local Development

For local development and testing:
.env
# AI Model API key (required)
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key

# Optional: Model configuration
MODEL_API_KEY=your_model_api_key
Local environment requires Chrome or Chromium to be installed on your system

​
Configuration File Template

Create a .env.example file in your project:
.env.example
# Copy this file to .env and fill in your values

# Browserbase (for production)
BROWSERBASE_API_KEY=
BROWSERBASE_PROJECT_ID=

# AI Models (choose at least one)
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
MODEL_API_KEY=

# Optional: Custom model endpoint
# MODEL_ENDPOINT=https://your-model-endpoint.com
Then copy and configure: 
cp .env.example .env
nano .env  # or use your preferred editor

​
Supported AI Models

Stagehand supports multiple AI model providers:

OpenAI

GPT-4, GPT-4 Turbo, GPT-5

Anthropic

Claude Sonnet, Claude Opus

Google

Gemini 2.0 Flash, Gemini Pro

Others

Groq, Azure OpenAI, and custom endpoints

​
Browser Environment Options

Stagehand can run in different browser environments:

​
Browserbase (Production)

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
});
Benefits:
  • No local Chrome installation needed
  • Scalable cloud infrastructure
  • Built-in debugging and observability
  • Optimized for production workloads

​
Local (Development)

const stagehand = new Stagehand({
  env: "LOCAL",
});
Benefits:
  • Fast iteration during development
  • No cloud costs
  • Full control over browser instance
  • Works offline

​
Optional Dependencies

Stagehand includes several optional dependencies for additional functionality:

​
Browser Automation Libraries

Install these if you want to use Stagehand with existing Playwright or Puppeteer code: 
npm install playwright-core

​
Additional AI Providers

Install provider-specific packages for enhanced functionality: 
# AWS Bedrock
npm install @ai-sdk/amazon-bedrock

# Google Vertex AI
npm install @ai-sdk/google-vertex

# Azure OpenAI
npm install @ai-sdk/azure

# Other providers
npm install @ai-sdk/groq @ai-sdk/mistral @ai-sdk/cerebras

​
Verification

Verify your installation by running a simple test:
test.ts
import { Stagehand } from "@browserbasehq/stagehand";

async function test() {
  const stagehand = new Stagehand({
    env: "LOCAL",
    verbose: 2,
  });

  try {
    await stagehand.init();
    console.log("✓ Stagehand initialized successfully!");

    const page = stagehand.context.pages()[0];
    await page.goto("https://example.com");
    console.log("✓ Browser navigation working!");
  } finally {
    await stagehand.close();
  }
}

test();
Run it: 
npx tsx test.ts
You should see: 
✓ Stagehand initialized successfully!
✓ Browser navigation working!

​
Troubleshooting

If you see an error about Node version, make sure you’re using Node.js ^20.19.0 or >=22.12.0:
node --version
Use nvm to manage Node versions:
nvm install 22
nvm use 22
If you see “Chrome not found” when using env: "LOCAL", install Chrome or Chromium:
brew install --cask google-chrome
If you can’t connect to Browserbase, verify:
  1. Your API key is correct
  2. Your project ID is valid
  3. You have an active Browserbase subscription
Test your credentials:
curl -X GET "https://api.browserbase.com/v1/projects" \
  -H "x-bb-api-key: YOUR_API_KEY"
If you encounter TypeScript errors, ensure you have the latest types:
npm install --save-dev @types/node
And verify your tsconfig.json includes:
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2022"
  }
}

​
Next Steps

Quickstart Guide

Run your first automation in minutes

Configuration

Learn about browser and model configuration

Core Methods

Explore act(), extract(), observe(), and agent()

Examples

View real-world automation examples
Need help? Join our Discord community or open an issue on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us