Eve

Install the native Browserbase extension in an existing Eve agent.

The @browserbasehq/eve package uses Eve’s native extension API. Mount it in an existing agent to add a persistent Stagehand browser with browserbase__run, browserbase__snapshot, and browserbase__screenshot tools.

This guide describes the 0.2 extension from PR #2821. That PR and the 0.2 release are pending. Version 0.1 has a different tool contract; use a locally packed 0.2 build when testing before release.

Prerequisites

• Node.js 24 or newer
• pnpm 10 or newer (use the checkout’s declared version when building from source)
• An existing agent on Eve >=0.39.3 <1 and its model-provider authentication
• A Browserbase API key

Install the extension

1. Add the package to your Eve project

   pnpm add @browserbasehq/eve@^0.2.0
   
2. Mount the extension

   Create agent/extensions/browserbase.ts:

   import browserbase from "@browserbasehq/eve";
   
   export default browserbase({
     apiKey: process.env.BROWSERBASE_API_KEY!,
   });
   

   Configure BROWSERBASE_API_KEY in the environment where your Eve agent runs. Eve discovers the extension and preserves its runtime dependencies automatically. Your existing agent retains its instructions and model configuration.

3. Build and run your agent

   pnpm exec eve build
   pnpm exec eve dev
   

   Ask the agent: Open https://example.com, take a snapshot, and report the page title.

Tools

Tool	Purpose
browserbase__run	Execute JavaScript with Playwright-shaped page, context, and browser objects, or perform snapshot-ID actions.
browserbase__snapshot	Inspect the active page and hydrate element IDs for subsequent actions.
browserbase__screenshot	Return an image of the active page.

Pass exactly one of code or actions to run. A snapshot displays IDs like [0-22]; an action uses the inner value, such as { "op": "click", "id": "0-22" }. Refresh the snapshot after navigation or when an ID becomes stale.

Eve’s built-in web_search and web_fetch remain available. The browser extension does not override them.

Stagehand runs JavaScript from browserbase__run in its browser extension, where it can access the authenticated browser session. Treat it as powerful browser-side code, not as a Node.js or hostile-code sandbox. See the security boundary.

Configuration

Pass options to browserbase() in the extension mount:

Option	Default	Purpose
apiKey	Required	Browserbase credential for browser sessions and Model Gateway.
model	openai/gpt-5.4-mini	Stagehand client model configuration; browser-only tool calls do not invoke it.
sessionTimeoutSeconds	900	Browserbase timeout, from 60 to 21,600 seconds.
proxies	false	Enable Browserbase proxies.

Set BROWSERBASE_PROJECT_ID in the runtime environment to select a non-default Browserbase project. Configure Eve’s agent model and its authentication separately; browser-only calls do not need a separate Stagehand model-provider key.

The extension uses Browserbase. It does not read the old example’s STAGEHAND_BROWSER, EVE_STAGEHAND_MODEL, or STAGEHAND_EVE_SESSION_FILE settings. Configure Eve’s own agent model separately.

Session lifecycle

The first browser tool call launches a session. The extension reuses it for later calls and serializes operations. The next call retries failed initialization; healthy sessions survive ordinary tool errors. Calling await browser.close() inside run releases the owned browser, and the next tool call creates a fresh session.

One Eve process shares browser resources, including pages, cookies, and authentication. Use separate processes for sessions that require isolation. Browserbase sessions use keepAlive: false and the configured session timeout.

Test an unreleased extension

From a checkout of the extension PR:

pnpm install --frozen-lockfile
pnpm exec turbo run build --filter @browserbasehq/eve
pnpm --filter @browserbasehq/eve pack --pack-destination /tmp

Install the resulting tarball in your Eve project with pnpm add /absolute/path/to/browserbasehq-eve-0.1.0.tgz. The source package version remains 0.1.0 until Changesets applies the pending 0.2 release. The tarball bundles the shared facade, so the consumer does not need the Stagehand monorepo.

Eve extension source

Read the native extension, configuration schema, and lifecycle implementation.