Skip to main content

Get started with Stagehand

Use npx create-browser-app for an interactive introduction to Stagehand.
1

Get your Browserbase API Key and Project ID

Your API key and Project ID are displayed in the Overview Dashboard:
Then copy your API Key directly from the input and update your .env by adding the BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID entries.
2

Get your OpenAI/Anthropic API Key

You can get your OpenAI/Anthropic API Key from the OpenAI Dashboard or Anthropic Dashboard.
3

Install Stagehand

  • npm
  • pnpm
  • yarn
npm install @browserbasehq/stagehand zod
4

Update your code or clone a template

Integrating Stagehand into your existing code is straightforward:
  • Node.js
import { z } from "zod/v3";
import { Stagehand } from "@browserbasehq/stagehand";

(async () => {
    // Initialize Stagehand
    const stagehand = new Stagehand({
      env: "BROWSERBASE",
      apiKey: process.env.BROWSERBASE_API_KEY,
      projectId: process.env.BROWSERBASE_PROJECT_ID!,
      model: "openai/gpt-4o",
      // Your OPENAI_API_KEY is automatically read from your .env
      // For how to configure different models, visit https://docs.stagehand.dev/configuration/models#first-class-models
  });
  await stagehand.init();
  const page = stagehand.context.pages()[0];
  await page.goto("https://docs.browserbase.com");

  // Preview an action before taking it
  const suggestions = await stagehand.observe("click 'Stagehand'");

  // Take a suggested action
  console.log(suggestions[0])
  await stagehand.act(suggestions[0]);

  // Read the NPM install command
  const { npmInstallCommand } = await stagehand.extract(
    "Extract the NPM install command",
    z.object({
      npmInstallCommand: z.string(),
    })
  );
  console.log(npmInstallCommand);
  
  await stagehand.close();
})().catch((error) => console.error(error.message));
Be sure to set your BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, and OPENAI_API_KEY environment variables to the values you copied.

5

Inspect the completed Session

You can find all the recent sessions on the Overview Dashboard, along with essential metrics:
Select your Session to inspect it with the Session Inspector.

​
Start building

Using Browser Sessions

Learn how to connect to and interact with browser sessions effectively.

Managing Sessions

Understand how to properly end sessions and manage their lifecycle.