Browser Agent Template

Template. Fork it, customize it, and deploy your own web-browsing agent.

---

Open-source agent that browses the real web. A Vercel eve agent with a web chat UI and a Browser Use cloud browser — one codebase, durable sessions, watch it browse live.

Features

Web Chat — Tasks in the Browser

Chat with your agent in the browser. Responses stream in, and every tool call (open browser, navigate, extract) renders inline as it happens.

Cloud Browser — The Real Web

The agent opens a real Browser Use cloud browser to navigate pages, scrape content, fill forms, click, and screenshot — no scraping APIs, the live web.

Watch It Work — Live Browser Panel

Every browsing session returns a liveUrl. The UI embeds it in a side panel, so you watch the agent's browser in real time, right next to the chat.

Hardened — Key Stays Server-Side

Your BROWSER_USE_API_KEY lives in the app runtime and is never exposed to the agent's sandbox or the model. Browsing is powered by @browser_use/eve.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Web chat (Next.js)                      │
└──────────────────────────────┬──────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────┐
│            eve agent (instructions, skill, tools)            │
│              mounted into Next.js via withEve()              │
└──────────────────────────────┬──────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────┐
│  @browser_use/eve — provisions a Browser Use cloud browser   │
│       (key stays server-side; agent drives it via CDP)       │
└──────────────────────────────┬──────────────────────────────┘
                               ▼
                     Browser Use cloud browser

It's a single Next.js service: withEve() in next.config.ts mounts the eve agent into the app, so the chat UI and the agent deploy together.

Quick Start

Deploy to Vercel

You'll be asked for a BROWSER_USE_API_KEY (from browser-use.com) and a model credential (link the Vercel project for the AI Gateway, or set AI_GATEWAY_API_KEY).

Self-hosting

Requirements: Node.js 24+

git clone https://github.com/browser-use/browser-agent-template.git
cd browser-agent-template

npm install
cp .env.example .env.local
npm run dev

Open http://localhost:3000 and ask: "Go to news.ycombinator.com and give me the top 5 posts."

Required environment variables:

BROWSER_USE_API_KEY=bu_...   # from browser-use.com
AI_GATEWAY_API_KEY=...        # or link a Vercel project for the AI Gateway

See ENVIRONMENT.md for the full reference.

Customization

See the Customization Guide for how to:

• Rename your agent and rewrite its instructions
• Change the AI model
• Add tools and skills
• Configure the cloud browser (proxy country, profile, timeouts)
• Set up auth for a public deployment
• Deploy your fork

How It Works

For the full technical deep-dive, see Architecture.

1. Chat: The web UI streams through eve's built-in Web Chat channel (useEveAgent).
2. Browse: On a web task, the agent loads the browser-use skill and calls open_cloud_browser.
3. Provision: @browser_use/eve spins up a Browser Use cloud browser (key stays server-side) and returns a liveUrl.
4. Drive: The agent drives the browser with browser-harness-js (raw, typed CDP) inside eve's sandbox.
5. Watch: The UI embeds the liveUrl in a side panel; stop_cloud_browser ends the session.

Development

npm run dev        # Start the dev server (Next.js + eve)
npm run typecheck  # TypeScript check
npm run build      # Production build

See AGENTS.md for notes aimed at AI coding assistants.

Built With

• eve — Durable agent framework
• @browser_use/eve — Browser Use cloud browser for eve
• Browser Use — Cloud browser infrastructure
• Next.js — React framework
• AI SDK — Model access

Contributing

See CONTRIBUTING.md for how to get involved.

License

MIT