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

ao dashboard [options]

Options

-p, --port · number

Port to listen on (overrides config)

--no-open · flag

Don’t open browser automatically

--rebuild · flag

Clean stale build artifacts and rebuild before starting

Basic Usage

# 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

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

Port Configuration

The dashboard reads the port from your config:

# agent-orchestrator.yaml
port: 3000

Override with --port:

ao dashboard --port 3001

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

lsof -ti :3000 | xargs kill

Auto-Open Browser

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

$ ao dashboard

Starting dashboard on http://localhost:3000

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

Disable with --no-open:

ao dashboard --no-open

Rebuild Mode

Use --rebuild to fix stale build issues:

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

Rebuild mode kills all processes on the port. Make sure no other services are using it.

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

# 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:

ao start

Use this for normal workflow — it starts everything.

ao dashboard

Starts only the dashboard:

ao dashboard

Use this when:

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

The dashboard can run without an orchestrator session. It will show agent sessions but the orchestrator features won’t work.

Environment Variables

The dashboard sets these automatically:

PORT · number

Dashboard port (from config or --port)

AO_CONFIG_PATH · string

Path to agent-orchestrator.yaml

TERMINAL_PORT · number

Port for tmux terminal proxy (if configured)

DIRECT_TERMINAL_PORT · number

Port for direct terminal access (if configured)

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:

# 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

Terminal view requires the terminal proxy to be configured. See Configuration for details.

Common Issues

No Config Found

Error: No agent-orchestrator.yaml found

Solution: Create a configuration:

ao init

Port Already in Use

Error: Port 3000 is already in use

Solution: Stop the existing server:

# Find and kill process
lsof -ti :3000 | xargs kill

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

Dashboard Not Built

Error: Could not find @composio/ao-web package.
Ensure it is installed: pnpm install

Solution: Install and build the dashboard:

cd packages/web
pnpm install
pnpm build

Module Not Found

Error: Cannot find module '@composio/ao-core'

Solution: Rebuild the dashboard:

ao dashboard --rebuild

Stale Build Cache

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:

ao dashboard --rebuild

Examples

Standard Usage

# Start dashboard
ao dashboard

# Browser opens to http://localhost:3000

Custom Port

# Start on port 3001
ao dashboard --port 3001

# Visit http://localhost:3001

Headless Mode

# Start without browser (for SSH sessions)
ao dashboard --no-open

Clean Start

# Clean rebuild
ao dashboard --rebuild

Development Workflow

# Terminal 1: Start orchestrator
ao start --no-dashboard

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

Production Mode

# Build production bundle
cd packages/web
pnpm build

# Start production server
ao dashboard

Dashboard URL Structure

# 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

Status

Monitor sessions from the CLI

Configuration

Configure dashboard port and features

Terminal Integration

Set up terminal proxy for live views