Skip to main content

​
Get Started in One Line

The fastest way to start with Stagehand: 
npx create-browser-app
This creates a new project with Stagehand pre-configured and ready to use.

​
Quick Setup Guide

Follow these steps to set up Stagehand and run your first automation:
1

Install Stagehand

Install Stagehand using your preferred package manager:
npm install @browserbasehq/stagehand
Stagehand requires Node.js version ^20.19.0 or >=22.12.0
2

Set Up Environment Variables

Create a .env file in your project root with your API keys:
# For Browserbase (recommended for production)
BROWSERBASE_API_KEY=your_browserbase_api_key
BROWSERBASE_PROJECT_ID=your_project_id

# For AI models (choose one)
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
Get your Browserbase credentials at browserbase.com
3

Create Your First Automation

Create a new file automation.ts and add this code:
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

async function runAutomation() {
  // Initialize Stagehand
  const stagehand = new Stagehand({
    env: "BROWSERBASE",
    apiKey: process.env.BROWSERBASE_API_KEY,
    projectId: process.env.BROWSERBASE_PROJECT_ID,
    model: {
      modelName: "openai/gpt-4.1",
      apiKey: process.env.OPENAI_API_KEY,
    },
    verbose: 2,
  });

  try {
    await stagehand.init();

    // Get the page
    const page = stagehand.context.pages()[0];
    await page.goto("https://github.com/browserbase");

    // Use natural language to click
    await stagehand.act("click on the stagehand repo");

    // Extract structured data
    const repoInfo = await stagehand.extract(
      "extract the repository description",
      z.object({
        description: z.string(),
        stars: z.string(),
      }),
    );

    console.log("Repository Info:", repoInfo);
  } finally {
    await stagehand.close();
  }
}

runAutomation();
4

Run Your Automation

Execute your automation script:
npx tsx automation.ts
Set verbose: 2 in your Stagehand config to see detailed logs of what’s happening

​
Local Development

For local development without Browserbase: 
const stagehand = new Stagehand({
  env: "LOCAL",
  verbose: 2,
  model: "openai/gpt-4.1",
});
Local environment requires Chrome/Chromium to be installed on your machine

​
Understanding the Code

Let’s break down the key parts of your first automation:

​
Initialization

const stagehand = new Stagehand({
  env: "BROWSERBASE",           // Use Browserbase cloud browsers
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  model: {
    modelName: "openai/gpt-4.1", // AI model for understanding pages
    apiKey: process.env.OPENAI_API_KEY,
  },
  verbose: 2,                    // Log level (0-2)
});

​
Navigation

const page = stagehand.context.pages()[0];
await page.goto("https://example.com");
Stagehand provides a CDP-based page interface optimized for automation.

​
Natural Language Actions

await stagehand.act("click on the stagehand repo");
The act() method uses AI to understand the page and execute actions.

​
Structured Extraction

const data = await stagehand.extract(
  "extract the repository description",
  z.object({
    description: z.string(),
    stars: z.string(),
  }),
);
The extract() method returns type-safe data matching your Zod schema.

​
Common Use Cases

Form Filling

Automate form submissions with natural language

Data Extraction

Extract structured data from any website

Web Navigation

Navigate complex websites automatically

Multi-Step Tasks

Use agents for complex automation workflows

​
Using the Agent

For multi-step tasks, use the agent: 
const agent = stagehand.agent();

const result = await agent.execute({
  instruction: "Find the latest pull request and extract its title",
  maxSteps: 20,
});

console.log(result.message);
Agents can take multiple actions autonomously to complete complex tasks.

​
Next Steps

Installation Guide

Detailed installation and configuration options

Core Methods

Learn about act(), extract(), observe(), and agent()

Configuration

Configure browsers, models, and logging

Best Practices

Optimize for cost, speed, and reliability
Pro tip: Start with verbose: 2 to understand what Stagehand is doing, then reduce to verbose: 0 for production.

Build docs developers (and LLMs) love

Get started for freeTalk to us