> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# ao dashboard

> Start the web dashboard for monitoring and managing agent sessions

The `dashboard` command starts the web interface for Agent Orchestrator. It provides real-time monitoring, session management, and visualization of agent activity.

## Syntax

```bash theme={null}
ao dashboard [options]
```

## Options

<ParamField path="-p, --port" type="number">
  Port to listen on (overrides config)
</ParamField>

<ParamField path="--no-open" type="flag">
  Don't open browser automatically
</ParamField>

<ParamField path="--rebuild" type="flag">
  Clean stale build artifacts and rebuild before starting
</ParamField>

## Basic Usage

```bash theme={null}
# Start dashboard (uses port from config)
ao dashboard

# Start on custom port
ao dashboard --port 3001

# Start without opening browser
ao dashboard --no-open

# Clean rebuild (fixes cache issues)
ao dashboard --rebuild
```

## Dashboard Features

The web dashboard provides:

* **Session List** - All active sessions across projects
* **Session Details** - Branch, issue, PR, CI status, activity
* **Terminal View** - Live tmux session output in browser
* **PR Integration** - View PR status, reviews, and CI checks
* **Real-Time Updates** - Server-Sent Events for live data
* **Activity Timeline** - Session history and events

<Tip>
  The dashboard is read-only for safety. Use the CLI for session management (spawn, kill, send).
</Tip>

## Port Configuration

The dashboard reads the port from your config:

```yaml theme={null}
# agent-orchestrator.yaml
port: 3000
```

Override with `--port`:

```bash theme={null}
ao dashboard --port 3001
```

<Note>
  If the port is busy, the command will fail. Stop the existing server first:

  ```bash theme={null}
  lsof -ti :3000 | xargs kill
  ```
</Note>

## Auto-Open Browser

By default, the dashboard opens in your browser once ready:

```bash theme={null}
$ ao dashboard

Starting dashboard on http://localhost:3000
```

The browser opens to `http://localhost:3000` after Next.js compiles.

Disable with `--no-open`:

```bash theme={null}
ao dashboard --no-open
```

## Rebuild Mode

Use `--rebuild` to fix stale build issues:

```bash theme={null}
ao dashboard --rebuild
```

This will:

1. **Kill Existing Server** - Stops any dashboard on the port
2. **Clean `.next` Directory** - Removes Next.js build cache
3. **Rebuild** - Next.js rebuilds from scratch
4. **Start** - Launches the dashboard

<Warning>
  Rebuild mode kills **all** processes on the port. Make sure no other services are using it.
</Warning>

### When to Use Rebuild

Use `--rebuild` when you see:

* **Module Not Found** - "Cannot find module '@composio/ao-core'"
* **Stale Imports** - Changes to core packages not reflected
* **Build Errors** - "Could not find a production build"
* **Cache Issues** - Old component code still running

```bash theme={null}
# Example error that needs rebuild
Error: Cannot find module './vendor-chunks/next.js'

# Solution
ao dashboard --rebuild
```

## Dashboard vs ao start

Two ways to start the dashboard:

### ao start

Starts **both** orchestrator and dashboard:

```bash theme={null}
ao start
```

Use this for normal workflow — it starts everything.

### ao dashboard

Starts **only** the dashboard:

```bash theme={null}
ao dashboard
```

Use this when:

* Orchestrator is already running
* You want to restart just the dashboard
* Testing dashboard changes

<Note>
  The dashboard can run without an orchestrator session. It will show agent sessions but the orchestrator features won't work.
</Note>

## Environment Variables

The dashboard sets these automatically:

<ParamField path="PORT" type="number">
  Dashboard port (from config or `--port`)
</ParamField>

<ParamField path="AO_CONFIG_PATH" type="string">
  Path to agent-orchestrator.yaml
</ParamField>

<ParamField path="TERMINAL_PORT" type="number">
  Port for tmux terminal proxy (if configured)
</ParamField>

<ParamField path="DIRECT_TERMINAL_PORT" type="number">
  Port for direct terminal access (if configured)
</ParamField>

## Dashboard Pages

### Home Page

`http://localhost:3000`

Shows:

* All projects
* Session count per project
* Quick links to spawn and status

### Sessions Page

`http://localhost:3000/sessions`

Shows:

* All sessions in a table
* Branch, PR, CI status, activity
* Filter by project

### Session Detail

`http://localhost:3000/sessions/<session-id>`

Shows:

* Session metadata
* Live terminal output
* PR details (if created)
* CI checks
* Review status
* Activity timeline

### Orchestrator Page

`http://localhost:3000/sessions/<prefix>-orchestrator`

The main orchestrator interface. Shows:

* All agent sessions
* Issue queue
* Notifications
* System events

## Terminal View

The dashboard embeds a terminal viewer for each session:

```bash theme={null}
# View session terminal
http://localhost:3000/sessions/ao-int-1234
```

Features:

* **Live Output** - Streams tmux pane content
* **Scroll History** - View past output
* **Read-Only** - Cannot send input (use CLI for that)
* **Auto-Refresh** - Updates every few seconds

<Note>
  Terminal view requires the terminal proxy to be configured. See [Configuration](/plugins/terminal/web) for details.
</Note>

## Common Issues

### No Config Found

```bash theme={null}
Error: No agent-orchestrator.yaml found
```

**Solution**: Create a configuration:

```bash theme={null}
ao init
```

### Port Already in Use

```bash theme={null}
Error: Port 3000 is already in use
```

**Solution**: Stop the existing server:

```bash theme={null}
# Find and kill process
lsof -ti :3000 | xargs kill

# Or use a different port
ao dashboard --port 3001
```

### Dashboard Not Built

```bash theme={null}
Error: Could not find @composio/ao-web package.
Ensure it is installed: pnpm install
```

**Solution**: Install and build the dashboard:

```bash theme={null}
cd packages/web
pnpm install
pnpm build
```

### Module Not Found

```bash theme={null}
Error: Cannot find module '@composio/ao-core'
```

**Solution**: Rebuild the dashboard:

```bash theme={null}
ao dashboard --rebuild
```

### Stale Build Cache

```bash theme={null}
Error: Module not found: ./vendor-chunks/next.js

This looks like a stale build cache issue. Try:

  ao dashboard --rebuild
```

**Solution**: Clean rebuild as suggested:

```bash theme={null}
ao dashboard --rebuild
```

## Examples

### Standard Usage

```bash theme={null}
# Start dashboard
ao dashboard

# Browser opens to http://localhost:3000
```

### Custom Port

```bash theme={null}
# Start on port 3001
ao dashboard --port 3001

# Visit http://localhost:3001
```

### Headless Mode

```bash theme={null}
# Start without browser (for SSH sessions)
ao dashboard --no-open
```

### Clean Start

```bash theme={null}
# Clean rebuild
ao dashboard --rebuild
```

### Development Workflow

```bash theme={null}
# Terminal 1: Start orchestrator
ao start --no-dashboard

# Terminal 2: Start dashboard in dev mode
cd packages/web
pnpm dev
```

### Production Mode

```bash theme={null}
# Build production bundle
cd packages/web
pnpm build

# Start production server
ao dashboard
```

## Dashboard URL Structure

```bash theme={null}
# Home
http://localhost:3000/

# All sessions
http://localhost:3000/sessions

# Specific session
http://localhost:3000/sessions/<session-id>

# Orchestrator
http://localhost:3000/sessions/<prefix>-orchestrator

# Project view
http://localhost:3000/projects/<project-id>
```

## Exit Codes

* `0` - Dashboard stopped gracefully
* `1` - Error (config not found, port busy, build failed)

## Next Steps

<CardGroup cols={2}>
  <Card title="Status" icon="chart-line" href="/cli/status">
    Monitor sessions from the CLI
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Configure dashboard port and features
  </Card>

  <Card title="Terminal Integration" icon="terminal" href="/configuration/terminal">
    Set up terminal proxy for live views
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.