Pi - Stagehand

The Pi integration gives a Pi agent native run, snapshot, and screenshot tools backed by one persistent Stagehand browser per Pi session. Pi ships without built-in MCP by design; extensions register tools directly, so this integration runs in process without an MCP server or bridge. The tool descriptions, runtime validators, and system prompt come from the shared facade contract, so the tools behave the same as the MCP-based integrations.

The extension uses Pi’s official package format. Browserbase must publish the first @browserbasehq/pi release before you can use the npm install below; use the source install below while testing an unreleased change.

Prerequisites

Node.js 24 or newer
A model-provider credential for Pi (OPENAI_API_KEY or ANTHROPIC_API_KEY)
A current Google Chrome installation for local browser mode

Quickstart

Install the Pi package

pi install npm:@browserbasehq/pi

Use pi install -l npm:@browserbasehq/pi to install only for the current project. Restart Pi after installing so it loads the extension.

Configure the Pi model

export OPENAI_API_KEY="your-openai-api-key"

Export ANTHROPIC_API_KEY instead to use an Anthropic model. This credential is for Pi’s own model, not the browser.

Choose the browser

The extension defaults to Browserbase when BROWSERBASE_API_KEY is set, otherwise it uses local Chrome:

export STAGEHAND_BROWSER="browserbase"
export BROWSERBASE_API_KEY="your-browserbase-api-key"

Run a browser task

pi --no-session -p "Open https://example.com and report the page title." </dev/null

Print mode reads piped stdin, so redirect </dev/null when running a one-shot task. A user-level pi install makes the extension available to future sessions. For project-local installs, complete Pi’s project trust flow interactively before running headless.

Try the extension from source

For development before the first release, build and install the package from the repository. The build bundles the private facade so installed consumers do not depend on the monorepo.

git clone https://github.com/browserbase/stagehand.git
cd stagehand
pnpm install --frozen-lockfile
pnpm exec turbo run build --filter @browserbasehq/pi
pi install ./packages/integrations/pi

Use pi list to inspect installed packages, pi update npm:@browserbasehq/pi to update a published installation, and pi remove npm:@browserbasehq/pi to remove it.

Configuration

Variable	Purpose
`OPENAI_API_KEY`	Credential for Pi’s own model.
`ANTHROPIC_API_KEY`	Alternative credential for Pi’s own model.
`STAGEHAND_BROWSER`	Select `local` or `browserbase`.
`BROWSERBASE_API_KEY`	Required for Browserbase.
`BROWSERBASE_PROJECT_ID`	Optional Browserbase project ID.
`STAGEHAND_MODEL_NAME`	Optional. The facade tools are deterministic and do not call a Stagehand model today.
`STAGEHAND_MODEL_API_KEY`	Optional credential for `STAGEHAND_MODEL_NAME`; the extension can infer a supported provider key from its environment.

Session lifecycle

The extension factory does not start a browser; factories also run in invocations that never start a session, such as pi --list-models. The browser launches lazily on the first tool call, relaunches if it closed, and closes on session shutdown. Shutdown awaits a still-pending launch before closing so it does not leak a racing launch. snapshot and run return text content. screenshot returns real image content because Pi supports multimodal tool results.

run executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the integration security boundary.

Pi integration source

Read the extension tool registrations and lazy browser lifecycle.

First steps

The basics

Configuration

Add-ons

Integrations

Best practices

Migration guide

SDK reference

Pi

Prerequisites

Quickstart

Try the extension from source

Configuration

Session lifecycle

Pi integration source

​Prerequisites

​Quickstart

​Try the extension from source

​Configuration

​Session lifecycle

Pi integration source

Prerequisites

Quickstart

Try the extension from source

Configuration

Session lifecycle