docs/src/app/dashboard/page.mdx
Monitor agent-browser sessions in real time with a local web dashboard showing a live browser viewport and command activity feed.
The dashboard is bundled into the binary and requires no separate install. Start the server and open any session:
agent-browser dashboard start
agent-browser open example.com
Then open http://localhost:4848 in your browser to see the live dashboard. If you expose the dashboard through a reverse proxy or port forward, explicitly allow its browser HTTPS origin when starting the server:
agent-browser dashboard start --allowed-origins https://dashboard.example.com
All sessions automatically stream to the dashboard. Local loopback origins are allowed automatically over IPv4 and IPv6 without an access token. For a reverse-proxied dashboard, use a comma-separated list of exact origins with --allowed-origins or AGENT_BROWSER_DASHBOARD_ALLOWED_ORIGINS; this lets the dashboard reject cross-origin requests and DNS-rebinding attacks. Every configured origin must be valid, and custom ports must be integers from 1 to 65535. Unknown options, missing values, invalid ports, and malformed origins fail without starting the server. The command prints private tokenized access URLs only for external origins. Open the matching URL once to establish the browser session and do not share it. Its unguessable token stays in the initial URL fragment, then the browser stores it in a Secure, host-bound, same-site cookie for dashboard API and stream requests. Open http://localhost:<port> directly for local access; the external token is never written to a loopback cookie. Configure the reverse proxy to redact cookies from logs. The browser stays on the dashboard origin while the server proxies per-session tabs, status, and stream traffic internally, so session ports do not need to be exposed. Repeated starts reuse the dashboard only when these settings match; stop it before changing the port or allowed origins.
By default each session binds its WebSocket stream server to an OS-assigned port. To use a specific port, set the AGENT_BROWSER_STREAM_PORT environment variable:
AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com
You can also use the runtime commands to control streaming on a running session:
agent-browser stream enable --port 9223
agent-browser stream status
agent-browser stream disable
The dashboard is a single-page web app with three areas:
<table> <thead> <tr> <th>Area</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><strong>Live viewport</strong></td> <td>Real-time JPEG frames from the browser, rendered to a canvas element</td> </tr> <tr> <td><strong>Activity feed</strong></td> <td>Chronological stream of commands, results, and console messages with expandable details</td> </tr> <tr> <td><strong>Session creation</strong></td> <td>Create new sessions from the dashboard with local engines (Chrome, Lightpanda) or cloud providers (AgentCore, Browserbase, Browserless, Browser Use, Kernel)</td> </tr> <tr> <td><strong>Status bar</strong></td> <td>Connection status, viewport dimensions, and WebSocket endpoint</td> </tr> </tbody> </table>The dashboard connects to the same WebSocket endpoint used by Streaming, with additional message types for observability:
Sent when a command begins executing:
{
"type": "command",
"action": "click",
"id": "r123",
"params": { "selector": "@e5" },
"timestamp": 1711367000000
}
Sent when a command finishes:
{
"type": "result",
"id": "r123",
"action": "click",
"success": true,
"data": {},
"duration_ms": 45,
"timestamp": 1711367000045
}
Sent when the browser logs to the console:
{
"type": "console",
"level": "log",
"text": "Page loaded",
"args": [{"type": "string", "value": "Page loaded"}],
"timestamp": 1711367000100
}
The args array contains the raw CDP Runtime.consoleAPICalled arguments for programmatic access. Object arguments include preview data (e.g. {userId: "abc", count: 42} instead of "Object").
These are in addition to the existing frame, status, and error message types documented on the Streaming page.
The dashboard is a Next.js static export (output: 'export') that produces plain HTML, CSS, and JS. It lives at packages/dashboard/ in the monorepo and is built with:
pnpm build:dashboard
The dashboard is embedded into the CLI binary at compile time using rust-embed. Plain HTTP requests serve the embedded dashboard assets and same-origin API routes. Session-specific tabs, status, and stream WebSocket traffic are proxied through the dashboard server to loopback-only session ports.
The dashboard includes an optional AI chat panel powered by the Vercel AI Gateway. When enabled, a Chat tab appears in the right pane alongside Activity, Console, Network, Storage, and Extensions.
The Chat tab is always visible. Set the API key to enable responses:
export AI_GATEWAY_API_KEY=gw_your_key_here
agent-browser dashboard start
Optionally override the gateway URL or model:
export AI_GATEWAY_URL=https://ai-gateway.vercel.sh # this is the default
export AI_GATEWAY_MODEL=openai/gpt-4o-mini # default: anthropic/claude-sonnet-4.6
The Rust server proxies chat requests from the dashboard to the Vercel AI Gateway and streams responses back using the Vercel AI SDK's UI Message Stream protocol. The dashboard frontend uses useChat from @ai-sdk/react with DefaultChatTransport.