Install Stagehand v3.7.1: The Playwright AI Guide

Two ways to get Stagehand, the AI browser automation framework from Browserbase, running on your machine. One is right, one wastes an hour. Let’s start there.

Option A: npx create-browser-app. Scaffolds a full project with example script, config file, and .env template. Takes 30 seconds.

Option B: npm install @browserbasehq/stagehand into an existing repo and wire it up yourself. Necessary when you’re bolting Stagehand onto a Next.js app or a CI job – but painful as a first-time install because the SDK expects Zod, a working Chromium, and specific env vars that aren’t obvious from the package alone.

Use Option A unless you’re integrating. That’s what the official quickstart recommends, and it’s the path this guide follows.

What you’re actually installing

Stagehand v3.7.1 (released 28 May 2026, per the GitHub releases page) is an open source AI browser automation framework that gives you four primitives – act, extract, observe, and agent – available in TypeScript and Python. It’s MIT-licensed, so no runtime cost from the framework itself. You still pay for the LLM.

Quick flag before you install anything: Cloudflare Browser Run currently supports @browserbasehq/stagehand v2.5.x only. Stagehand v3 and later are not supported there – v3 is not Playwright-based. If your target runtime is Cloudflare Workers, pin to v2.5.x and stop here. Everywhere else, v3 is the default.

System requirements

It’s a Node or Python package that drives a browser. Specs below reflect what the official SDKs declare as of May 2026.

RAM is whatever Chromium wants – plan for ~1 GB free per active browser session. Multiply if you run agents in parallel.

Install Stagehand (TypeScript, the recommended path)

The scaffold command creates a project you can run in under a minute.

npx create-browser-app
cd my-stagehand-app
cp .env.example .env # add your keys
npm install
npm start

Follow the CLI prompts to enter the project directory and add your API keys, then run the example script. The scaffold pre-writes index.ts, a config file, and a working example that hits stagehand.dev. If you’re integrating into an existing TypeScript codebase instead, use the manual path:

npm install @browserbasehq/stagehand zod
npx playwright install # only if running locally

Zod is a hard dependency for schema-typed extraction, and playwright install downloads the Chromium binary Stagehand controls. Skip the Playwright step only if you’re going straight to Browserbase cloud.

First-time configuration

Your .env needs three things at most. Two if you’re local-only.

# .env
MODEL_API_KEY="sk-..." # OpenAI, Anthropic, or Gemini
BROWSERBASE_API_KEY="bb-..." # only for cloud mode
STAGEHAND_API_URL="https://api.stagehand.browserbase.com" # optional

Watch the env var name. Recent releases prefer STAGEHAND_API_URL for API overrides while retaining STAGEHAND_BASE_URL as a deprecated fallback. Old tutorials still use the deprecated name – it works for now, but will vanish. Same story with browserbase_project_id: deprecated, accepted for backwards compatibility, and silently ignored. If you’re following a blog post from 2024, half its config will parse into nothing.

The minimum viable script:

import "dotenv/config";
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();
const page = stagehand.context.pages()[0];
await page.goto("https://example.com");
await stagehand.act("click the More information link");
await stagehand.close();

Switch env: "LOCAL" to env: "BROWSERBASE" when you’re ready for cloud sessions – that’s the entire migration.

Verify the install

Run the scaffold’s default script:

npm start

You should see a browser window pop up (local mode) or a session URL printed to stdout (cloud mode). If the LLM call succeeds, Stagehand logs the extraction result. If it fails silently after a minute, that’s the default timeout – see the errors section.

Before running agent.execute() on anything real: call observe() first. It returns what Stagehand thinks is actionable without spending tokens on execution – and lets you cache the resolved action so future runs skip the LLM entirely.

Common errors and the actual fixes

Four failure modes account for most first-run problems.

1. “Warning: found N iframe(s) on the page” – Stagehand emits this at INFO level and then silently ignores the iframe content. The fix: set iframes: true when you want it to descend into embedded frames. If your extract returns empty, check for this first.
2. Requests hang, then 429 or timeout – Connection errors, 408, 409, 429, and 5xx responses are retried 2 times by default with a short exponential backoff, and requests time out after 1 minute (per the Python SDK docs). Long agent workflows blow past this. Bump max_retries per-request or raise the timeout on the client.
3. “Cannot find module ‘@browserbasehq/stagehand'” after upgrade – You upgraded the package but your virtualenv or node_modules is stale. If you’ve upgraded to the latest version but aren’t seeing new features, your environment is likely still using an older version. Nuke node_modules or the Python venv and reinstall.
4. Cloudflare Worker deploy breaks on v3 – Pin to @browserbasehq/stagehand@^2.5 in that specific environment. Cloudflare Browser Run’s docs confirm v3+ is out of scope until they track the new CDP-based engine.

That last one deserves a moment’s thought. The v2→v3 jump wasn’t a version bump – Browserbase replaced Playwright as the underlying transport with a CDP-native engine. The API surface looks almost identical, which is exactly why the breakage is invisible until deploy time. If a tool in your stack claims to support Stagehand and hasn’t updated docs since early 2025, assume it means v2.

Upgrading and uninstalling

Upgrades on the TypeScript SDK are straightforward:

npm update @browserbasehq/stagehand
npx playwright install # re-pull the matching Chromium
npm ls @browserbasehq/stagehand # verify version

Uninstall is the mirror:

npm uninstall @browserbasehq/stagehand zod
rm -rf ~/.cache/ms-playwright # remove Chromium binaries
rm .env

For Python: pip uninstall stagehand-py and delete the venv. Nothing writes outside your project directory except the Playwright browser cache.

What most tutorials leave out

Every guide teaches you act, extract, and observe. Almost none mention that the newer CUA (computer-use agent) models – openai/gpt-5.4-mini, openai/gpt-5.5, and anthropic/claude-haiku-4-5, added in a recent release – behave differently from plain chat models. They’re built for pointer-and-keyboard reasoning. If you’re paying for GPT-4o to click buttons, you’re overpaying and getting worse results. Swap the model name in your config and re-run.

FAQ

Do I need a Browserbase account to use Stagehand?

No. Stagehand works locally with any Chromium browser. Browserbase adds production features – session replay, captcha solving – but the core SDK runs fine without an account.

Can I use a local Ollama model instead of OpenAI or Anthropic?

Officially, no. The SDK routes through the Vercel AI SDK, which supports OpenAI, Anthropic, and Google Gemini as first-class providers. Some community setups proxy Ollama behind an OpenAI-compatible endpoint by pointing baseURL at localhost – but this isn’t documented and results on smaller open models are noticeably worse for DOM reasoning tasks. Fine for prototyping, not for production.

Which language SDK should I pick?

TypeScript if you’re starting fresh – it’s the reference implementation, ships features first, and the ecosystem around it (Zod schemas, the Vercel AI SDK integrations) is what Browserbase actually tests against. Python is stable and full-featured if that’s your environment. Go is available at v3.21.0 but remains alpha, so treat it as experimental: check the stagehand-go README for current limitations before committing it to anything that runs in production. The short version: TypeScript for new projects, Python if you’re in a Python stack, Go only if you’ve read the caveats.

Next: open your scaffold’s index.ts, replace the example URL with a page you actually need to automate, and run observe() against it. If the returned actions look sane, cache them and wire up act(). That’s the shortest path from install to something useful.