> ## Documentation Index
> Fetch the complete documentation index at: https://stagehand-agent-productionize-eve-0-2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Eve

> Install the native Browserbase extension in an existing Eve agent.

The `@browserbasehq/eve` package uses Eve’s native [extension API](https://eve.dev/docs/extensions). Mount it in an existing agent to add a persistent Stagehand browser with `browserbase__run`, `browserbase__snapshot`, and `browserbase__screenshot` tools.

<Note>
  This guide describes the 0.2 extension from [PR #2821](https://github.com/browserbase/stagehand/pull/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.
</Note>

## 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

<Steps>
  <Step title="Add the package to your Eve project">
    ```bash theme={null}
    pnpm add @browserbasehq/eve@^0.2.0
    ```
  </Step>

  <Step title="Mount the extension">
    Create `agent/extensions/browserbase.ts`:

    ```ts theme={null}
    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.
  </Step>

  <Step title="Build and run your agent">
    ```bash theme={null}
    pnpm exec eve build
    pnpm exec eve dev
    ```

    Ask the agent: `Open https://example.com, take a snapshot, and report the page title.`
  </Step>
</Steps>

## 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.

<Warning>
  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](/v4/integrations/overview#security-boundary).
</Warning>

## 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:

```bash theme={null}
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.

<Card title="Eve extension source" icon="github" href="https://github.com/browserbase/stagehand/tree/main/packages/integrations/eve">
  Read the native extension, configuration schema, and lifecycle implementation.
</Card>