Eve

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.

Prerequisites

Node.js 24 or newer
pnpm 10 or newer
An existing agent on Eve 0.68.x and its model-provider authentication
A Browserbase API key

Install the extension

Add the package to your Eve project

pnpm add @browserbasehq/eve@^0.2.0

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.

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`	`BROWSERBASE_API_KEY`	Browserbase credential, resolved when the first browser tool runs.
`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`	Browserbase default	Omit to use Browserbase’s default; set `true` or `false` to override.

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.

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.

Eve extension source

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

First steps

The basics

Configuration

Add-ons

Integrations

Best practices

Migration guide

SDK reference

Prerequisites

Install the extension

Tools

Configuration

Session lifecycle

Eve extension source

​Prerequisites

​Install the extension

​Tools

​Configuration

​Session lifecycle

Eve extension source

Prerequisites

Install the extension

Tools

Configuration

Session lifecycle