# Observability Dashboard

Monitor agent-browser sessions in real time with a local web dashboard showing a live browser viewport and command activity feed.

## Usage

The dashboard is bundled into the binary and requires no separate install. Start the server and open any session:

```bash
agent-browser dashboard start
agent-browser open example.com
```

Then open `http://localhost:4848` or a proxied/forwarded dashboard URL such as `https://dashboard.agent-browser.localhost` in your browser to see the live dashboard.

All sessions automatically stream to the dashboard. No extra flags are needed. 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.

### Custom stream port

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:

```bash
AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com
```

You can also use the runtime commands to control streaming on a running session:

```bash
agent-browser stream enable --port 9223
agent-browser stream status
agent-browser stream disable
```

## Dashboard features

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>

## WebSocket protocol

The dashboard connects to the same WebSocket endpoint used by [Streaming](/streaming), with additional message types for observability:

### Command events

Sent when a command begins executing:

```json
{
  "type": "command",
  "action": "click",
  "id": "r123",
  "params": { "selector": "@e5" },
  "timestamp": 1711367000000
}
```

### Result events

Sent when a command finishes:

```json
{
  "type": "result",
  "id": "r123",
  "action": "click",
  "success": true,
  "data": {},
  "duration_ms": 45,
  "timestamp": 1711367000045
}
```

### Console events

Sent when the browser logs to the console:

```json
{
  "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](/streaming) page.

## Architecture

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:

```bash
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.

## AI Chat

The dashboard includes an optional AI chat panel powered by the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). When enabled, a **Chat** tab appears in the right pane alongside Activity, Console, Network, Storage, and Extensions.

### Setup

The Chat tab is always visible. Set the API key to enable responses:

```bash
export AI_GATEWAY_API_KEY=gw_your_key_here
agent-browser dashboard start
```

Optionally override the gateway URL or model:

```bash
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
```

### How it works

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

<table>
  <thead>
    <tr><th>Variable</th><th>Description</th><th>Default</th></tr>
  </thead>
  <tbody>
    <tr><td><code>AI_GATEWAY_URL</code></td><td>Vercel AI Gateway base URL.</td><td><code>https://ai-gateway.vercel.sh</code></td></tr>
    <tr><td><code>AI_GATEWAY_API_KEY</code></td><td>API key for the AI Gateway. Required to enable AI chat responses.</td><td>(none)</td></tr>
    <tr><td><code>AI_GATEWAY_MODEL</code></td><td>Default AI model for chat requests.</td><td><code>anthropic/claude-sonnet-4.6</code></td></tr>
  </tbody>
</table>