Guide · Open source
How to use Stagehand: install, run and extract data
Updated · written with AI from the project's own documentation and checked against our catalogue data
Stagehand is an open-source SDK, licensed under MIT, that lets your code drive a real web browser using plain-language instructions alongside Playwright-style methods. It is aimed at developers and teams who need to work with sites they do not control, or pull structured data from pages that have no API. After this guide you will know how to install it, run observe, act and extract calls, and keep login sessions between runs.
Stagehandbrowserbase/stagehand · ★ 25.9k · MIT Install options & downloads Quick start
- 1Install the package. Run the install command for your language: pnpm, pip or go get, as shown in the README.
- 2Install Google Chrome. Local runs need Chrome installed on the machine.
- 3Set your model API key. Export a key for a supported provider such as OpenAI, for example as OPENAI_API_KEY.
- 4Launch a local browser. Call localBrowser.launch with a userDataDir so cookies persist between runs.
- 5Create a Stagehand instance. Pass the browser and a model name and key to Stagehand.create.
- 6Run observe, act and extract. Use observe to find selectors, act for clicks and navigation, and extract with a schema for structured data.
- 7Close the session. Call stagehand.close() and browser.close() when the run finishes.
What you need before you start
Stagehand is installed through a package manager. You need Node.js for the TypeScript package, Python for the Python package, or Go for the Go module, depending on which language you use.
For local browser runs you need Google Chrome installed. You also need an API key for a supported model provider, such as OpenAI, because Stagehand sends instructions to a model.
- Node.js (TypeScript package)
- Python (Python package)
- Go (Go module)
- Google Chrome for local browser runs
- An API key for a supported model provider such as OpenAI
Install Stagehand for TypeScript, Python or Go
Pick the package for your language. The TypeScript install also pins zod to a specific range, as the README shows.
For full setup details, the README points to the official Quickstart at docs.stagehand.dev.
pnpm add @browserbasehq/stagehand 'zod@~4.4.3'
pip install stagehand
go get github.com/browserbase/stagehand/packages/sdk-go/v4@v4.0.0Launch a browser and keep your session
Stagehand starts a local browser with localBrowser.launch in TypeScript, or local_browser.launch in Python. Passing a userDataDir makes cookies persist in that folder, so the next run starts already signed in. The README uses ./browser-data as the example folder.
const browser = await localBrowser.launch({ userDataDir: "./browser-data" });Create a Stagehand instance with a model
Stagehand.create takes the browser and a model configuration. The README example uses the model name openai/gpt-5.4-mini and reads the key from the OPENAI_API_KEY environment variable. Keep keys out of your source code.
const stagehand = await Stagehand.create({
browser,
model: { modelName: "openai/gpt-5.4-mini", apiKey: process.env.OPENAI_API_KEY },
});Observe, act and extract on a page
Use observe to find elements. It returns selectors you can pass to Playwright-style locators, so you can fill fields without sending credentials to the model. Use act to perform an action described in plain language, such as clicking a button. Use extract to pull data into a schema you define; the README uses zod in TypeScript and Pydantic models in Python.
The README says act self-heals when a site changes its layout, so a plain-language instruction can keep working after a redesign.
- observe: finds elements and returns their selectors
- act: performs an action such as clicking a button or opening a page
- extract: returns data validated against your schema
const { data: email } = await stagehand.observe("find the email input");
await page.locator(email[0].selector).fill(process.env.APP_EMAIL!);
await stagehand.act("click the sign in button");
const { data } = await stagehand.extract("extract every invoice in the table", schema);Close the session cleanly
Always close the Stagehand instance and then the browser when you are done. The README examples call stagehand.close() and browser.close() at the end of the script, and the Python example does this in finally blocks.
await stagehand.close();
await browser.close();What people use it for
- Logging into a web app once and reusing the session in later runs
- Extracting every row of an invoice table into typed fields
- Navigating a site you do not control, such as clicking through to a billing page
- Adding AI-assisted steps to an existing Playwright-style workflow
Frequently asked questions
Is Stagehand free to use?
Stagehand is released under the MIT licence, as stated in the README and project listing. You still need an API key from a model provider such as OpenAI, and that provider's billing applies to your model calls.
What do I need to install Stagehand?
You need Node.js for the TypeScript package, Python for the Python package, or Go for the Go module. For local browser runs you also need Google Chrome, plus an API key for a supported model provider.
How do I install Stagehand with npm or pnpm?
The README uses pnpm: run pnpm add @browserbasehq/stagehand 'zod@~4.4.3'. For Python, use pip install stagehand. For Go, use go get github.com/browserbase/stagehand/packages/sdk-go/v4@v4.0.0.
Why does Stagehand need Chrome?
The README says local runs need Google Chrome installed. Stagehand drives a real browser, so it needs one on the machine running the script.
Can Stagehand keep me logged in between runs?
Yes. Passing a userDataDir such as ./browser-data to localBrowser.launch stores cookies in that folder, so the next run can start already signed in.
How does Stagehand compare to Playwright or Puppeteer?
Stagehand uses Playwright-style methods such as goto, click and locator, and adds plain-language observe, act and extract steps. If you only need fixed scripted browser tests with no AI, the README suggests a plain Playwright or Puppeteer setup may fit better.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Stagehand suits developers who already know Playwright and want model-driven steps on sites they do not control, or who need structured data from pages without an API. It is a poor fit for fixed scripted tests with no AI, or for non-programmers, since it needs code and a model API key. Consider Playwright, Puppeteer, Browser Use or Skyvern if you want a different approach.
Install options & downloads