Add BrowseCLI in an E2B sandbox

[shrey150]

Browser agent in an E2B sandbox

A deep-research agent (Vercel AI SDK) that uses an E2B sandbox as its tool surface. The agent loop runs on the host; its single bash tool executes commands inside the sandbox via sandbox.commands.run. The sandbox image (browsecli-sandbox) has the Browserbase browse CLI installed, so the agent does its research by running browse commands; browse drives a browser that runs remotely on Browserbase over CDP — no Chrome runs in the sandbox.

host (index.ts)                E2B sandbox                Browserbase
AI SDK agent loop  ── bash ──▶  browse CLI   ── CDP/wss ──▶  remote browser

This is the idiomatic "sandbox as a tool" shape: the agent reasons on the host, and the sandbox is the isolated place where its commands actually run.

The default task is a product-research example: search Amazon (https://www.amazon.com) for the current top mechanical keyboards and return a comparison of the top 5 results — each product's title, price, star rating, number of ratings, and its product URL. It is deliberately browser-only: Amazon search returns no products to a plain curl, so the agent has to drive a real browser to get the data. The agent plans its own steps — there are no site-specific instructions in the prompt. Override the goal with the TASK env var.

What changed in this revision

• Minimal, self-teaching system prompt. The system prompt no longer documents browse subcommands or flags. It tells the agent that a browse CLI is installed and pre-configured via env vars, instructs it to learn the CLI by running browse skills show (the CLI's bundled usage guide, shipped in browse ≥ 0.9.5 — now released), with browse --help as a supplementary reference, and gives one citation rule (link the document itself, not a viewer/index page).
• Prompt hardened for sandbox reality. Three additions: (1) an environment fact — the agent is in a sandbox with no local browser, sessions are remote and env-configured, so it must never pass --local; (2) today's date is interpolated into the prompt at runtime (new Date().toISOString().slice(0, 10)), so the model never guesses or hardcodes a date; (3) an answer-of-record rule — if nearing the step limit, stop navigating and give the best final answer from what's been gathered.
• Env-steered shared session (no flags). The sandbox gets two env vars via Sandbox.create(template, { envs }): BROWSERBASE_API_KEY (auth) and BROWSE_SESSION=agent. With both set, every browse command defaults to the remote Browserbase browser and shares one session — the agent never needs --remote or --session (though it may still pass its own named session, which also works).
• Bash tool description simplified to a generic "Run a bash command in the sandbox and return its output" (no more browse/flag specifics baked into the tool).
• Host-driven pattern + secure key injection (unchanged): the AI SDK agent loop runs on the host with a single bash tool that execs inside the sandbox via sandbox.commands.run; BROWSERBASE_API_KEY only ever lives in the sandbox env, never on disk.

Files

File	Purpose
index.ts	The whole example: creates the sandbox, runs the AI SDK agent loop on the host, exposes a bash tool that execs inside the sandbox.
e2b.Dockerfile	Template image: FROM ghcr.io/browserbase/browse (the official prebuilt CLI image, node:20-slim + browse). No Chrome.
e2b.toml	E2B template config.
package.json	Deps (e2b, ai, @ai-sdk/anthropic, zod, tsx, dotenv).
env.template	E2B_API_KEY, ANTHROPIC_API_KEY, BROWSERBASE_API_KEY.

E2E Test Matrix

Run against released artifacts (browse 0.9.5, published to npm and ghcr.io/browserbase/browse:latest): template rebuilt from the committed e2b.Dockerfile, then the example executed exactly as written on this branch (npm install of the committed package.json, npm start, default Amazon task) on real E2B cloud + a live remote Browserbase browser + host model claude-sonnet-5.

Command / flow	Observed output	Confidence / sufficiency
Registry check: docker run --rm ghcr.io/browserbase/browse browse --version, browse skills show, browse --help	browse/0.9.5; skills show prints the bundled skill (frontmatter + usage guide); --help leads with the "Start here (for AI agents): browse skills show" header.	Proves the public image :latest now serves 0.9.5 with the discovery surface the example's prompt depends on.
e2b template create browsecli-sandbox --dockerfile e2b.Dockerfile ... (rebuild from the committed Dockerfile), then in-sandbox plumbing: browse --version, browse skills show | head -5, browse --help | head -8	Template built in 34s from ghcr.io/browserbase/browse:latest; a sandbox created from it reports browse/0.9.5 linux-x64, skills show prints the skill, --help shows the agent header.	Proves the exact committed image path delivers released 0.9.5 inside a real E2B sandbox.
npm start (full agent run, default Amazon task; host AI SDK loop → sandbox bash tool → browse → remote Browserbase)	First tool call was browse skills show. Then browse open "https://www.amazon.com/s?k=mechanical+keyboard" --remote --session <name>, a series of browse eval extractions, and a product-page spot-check. 14/40 steps, 13 tool calls, 0 errored calls, ~120s wall-clock. Printed ===== FINAL ANSWER ===== with a 5-row comparison table — title, price, star rating, # of ratings, canonical amazon.com/dp/<ASIN> URL per row — plus methodology notes (sponsored listings excluded) and the run's date (injected at runtime) cited in the header.	Proves the example runs end-to-end as written on released 0.9.5: the agent learns the CLI from browse skills show first, never passes --local, stays well under the 40-step cap, and produces a complete, correct-format answer.
Cleanup: Browserbase sessions API status=RUNNING + e2b sandbox list after the run	[] and "No sandboxes found".	Confirms the run tears down both the remote browser session and the sandbox — no leaked resources.

🤖 Generated with Claude Code

[cla-bot]

We require contributors to sign our Contributor License Agreement, and we don't have @shrey150 on file. You can sign our CLA at https://e2b.dev/docs/cla . Once you've signed, post a comment here that says '@cla-bot check'

[shrey150]

@cla-bot check

[cla-bot]

The cla-bot has been summoned, and re-checked this pull request!

[shrey150]

Updated: the agent's system prompt now points it at browse skills show first — the CLI's bundled usage guide — with browse --help kept as a supplementary reference. browse skills show ships in the next browse release; this example already tracks ghcr.io/browserbase/browse, so it'll pick it up automatically once released.

[shrey150]

browse@0.9.5 is now released (npm + ghcr.io/browserbase/browse:latest), including the browse skills show command this example's prompt relies on — so the example now runs end-to-end exactly as written.

Verified against the released artifacts: rebuilt the browsecli-sandbox template from the committed e2b.Dockerfile (picks up 0.9.5 from :latest), confirmed browse --version → 0.9.5 inside a sandbox, and ran npm start with the default Amazon task. The agent's first tool call was browse skills show, it completed in 14/40 steps (~2 min) with zero errored tool calls, and returned the full 5-product comparison table. Updated the E2E matrix in the PR body with these runs and marking the PR ready for review.