Add guides/browser-agent-in-sandbox: a browser-research agent in a Vercel Sandbox

[shrey150]

What

Adds guides/browser-agent-in-sandbox — a full-stack Next.js app where an autonomous browser-research agent drives the browse CLI inside a Vercel Sandbox and streams its steps to the UI live: enter a prompt, watch each browse step stream in, get a final comparison table.

Demo: browser-agent-in-sandbox.vercel.app

How it works

Next.js app (/api/chat agent loop, AI SDK streamText)
   --bash--> Vercel Sandbox microVM (browse CLI runs here)
                 --CDP/wss--> Browserbase cloud browser (navigates / reads pages)
UI (useChat) renders each browse step + final answer

• The agent loop runs in the /api/chat route: it provisions a sandbox, builds a bash tool with bash-tool bound to that sandbox, and runs the AI SDK's streamText with stopWhen: stepCountIs(40). The model navigates the web by emitting browse commands that execute inside the microVM.
• The browse CLI drives a real browser on Browserbase — the browser never runs in the sandbox, only the CLI does, so the microVM stays cheap and the browser stays fully managed.
• Keyless model via AI Gateway: the bare model string anthropic/claude-sonnet-5 resolves through the default Gateway provider in ai@6, authenticated by the deployment's VERCEL_OIDC_TOKEN. The same Vercel auth powers both the Sandbox and the model — there is no separate Anthropic key. The only secret is BROWSERBASE_API_KEY.
• Live streaming UI: useChat from @ai-sdk/react renders each browse tool call (running/done/error) as it happens, and the final answer as Markdown.
• Self-teaching, sandbox-aware system prompt, built fresh per request (buildSystemPrompt()): it points the model at browse skills show (the CLI's bundled usage guide, shipped in browse ≥ 0.9.5) to learn the CLI itself, states the environment fact (sandbox microVM, no local browser, sessions remote and env-configured — never pass --local), injects today's date at request time so the model never guesses a date, and instructs the agent to give its best final answer from what it has gathered when nearing the step limit.

Sandbox image (dual-mode)

The route runs in two modes:

• Template image (faster cold start): the included Dockerfile bakes browse into a sandbox image pushed to the project's Vercel Container Registry. Set BROWSE_VCR_IMAGE and the route boots from it, skipping the per-request install.
• Runtime install (default): when BROWSE_VCR_IMAGE is unset, the route boots node24 and runs npm install -g browse per request.

A one-click Deploy with Vercel button and full setup/build instructions are in the README. A headless smoke harness (pnpm smoke, scripts/smoke.ts) exercises the same runBrowserAgent path as /api/chat against real cloud.

E2E Test Matrix

Run against released artifacts (browse 0.9.5, published to npm and ghcr.io/browserbase/browse:latest), executing the example as committed on this branch (runtime-install path, default Amazon task, real Vercel Sandbox + AI Gateway + Browserbase).

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; --help leads with the "Start here (for AI agents): browse skills show" header.	Proves the public image behind the Dockerfile/VCR path now serves 0.9.5 with the discovery surface the prompt depends on.
Runtime-install plumbing: Sandbox.create({ runtime: 'node24' }) + npm install -g browse@latest, then browse --version, browse skills show | head -5, browse --help | head -8 in-sandbox	Install exit 0; browse/0.9.5 linux-x64 node-v24; skill frontmatter printed; agent-facing help header present.	Proves the route's default (no BROWSE_VCR_IMAGE) install path delivers released 0.9.5 inside a real Vercel Sandbox.
pnpm smoke (full agent run through the same runBrowserAgent as /api/chat; default Amazon task; model via AI Gateway OIDC)	First tool call was browse skills show. Then browse open "https://www.amazon.com/s?k=mechanical+keyboard" --remote --session <name>, browse snapshot, extraction steps, and the agent's own browse stop --session <name> — 10 bash calls, well under the 40-step cap, ~120s wall-clock, exit 0. Printed ===== FINAL ANSWER ===== with a 5-row comparison table (title, price, star rating, # of ratings, canonical amazon.com/dp/<ASIN> URL per row), sponsored placements excluded.	Proves the agent path runs end-to-end as written on released 0.9.5: learns the CLI from browse skills show first, never passes --local, keyless model via Gateway, complete correct-format answer.
Regression that motivated the pnpm smoke script: plain tsx scripts/smoke.ts	ERR_PACKAGE_PATH_NOT_EXPORTED: No "exports" main defined in bash-tool/package.json — this package is CJS-scoped and bash-tool@1.3.17 is ESM-only (import condition only), so the previously documented invocation cannot resolve it (the Next.js app itself is unaffected — its bundler uses the import condition).	Demonstrates the failure mode the new smoke script (tsx --conditions=import) fixes; the passing run above is the proof.
pnpm type-check (tsc --noEmit)	Exit 0 with the buildSystemPrompt() refactor.	Supporting: the prompt change is type-safe across the route, agent, and smoke harness.
Cleanup: Browserbase sessions API status=RUNNING after the run	[]	Confirms the run tears down the remote browser session; the sandbox is stopped by onFinish.
(Prior revision) deployed demo: curl -N -X POST <demo>/api/chat, VCR image readiness probe, two vercel deploy --prod builds	Streamed browse tool calls + final comparison table end-to-end from the deployment; VCR image booted with browse on PATH; production builds clean.	Validated the deployed/VCR path on the then-current CLI (0.9.1); the deployed demo's baked image predates 0.9.5 — rebuilding the VCR image from the committed Dockerfile picks up 0.9.5, as shown by the registry row.

Supersedes #1517 — reworked from solutions/ into a full-stack deployable guide under guides/ (where the Sandbox examples live), with a live Demo, a Deploy button, and a VCR template image.

🤖 Generated with Claude Code

[vercel]

@shrey150 is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
mintlify-docs-rewrite	Error		Jul 7, 2026 6:29pm

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​vercel/​sandbox@​2.3.0
	npm/​bash-tool@​1.3.17
	npm/​just-bash@​3.0.2
	npm/​streamdown@​1.6.11
	npm/​eslint@​10.6.0

View full report

[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's runtime-install path pulls browse@latest and the VCR image path tracks ghcr.io/browserbase/browse, so both 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 as written.

Verified against the released artifacts: the route's default runtime-install path (node24 sandbox + npm install -g browse@latest) now serves 0.9.5 inside a real Vercel Sandbox, and a full headless run through the same runBrowserAgent path as /api/chat (default Amazon task, keyless model via AI Gateway) completed in 10 bash calls (~2 min) with zero errors — first tool call was browse skills show, final answer was the full 5-product comparison table.

One fix surfaced by this pass: bash-tool is ESM-only while this package is CJS-scoped, so the documented plain tsx scripts/smoke.ts invocation couldn't resolve it (the Next.js app itself is unaffected). Added a pnpm smoke script that runs tsx with --conditions=import. E2E matrix in the PR body updated; marking ready for review.