Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us