ao start / ao stop

Start and stop the orchestrator agent and web dashboard

The start and stop commands manage the orchestrator agent and web dashboard lifecycle.

ao start

Start the orchestrator agent and dashboard for a project.

Syntax

ao start [project]

Arguments

project · string

Project ID from config, or a GitHub repository URL for quick onboarding

If you have only one project configured, the project argument is optional.

Options

--no-dashboard · flag

Skip starting the dashboard server

--no-orchestrator · flag

Skip starting the orchestrator agent session

--rebuild · flag

Clean and rebuild dashboard before starting (fixes cache issues)

Basic Usage

# Start with single project config
ao start

# Start specific project
ao start my-project

# Start without dashboard
ao start --no-dashboard

# Start with clean rebuild
ao start --rebuild

Quick Start from URL

Start directly from a GitHub repository URL:

# Clone repo, generate config, and start
ao start https://github.com/owner/repo

# Short syntax
ao start owner/repo

This will:

1. Parse the repository URL
2. Clone the repository (shallow clone, depth 1)
3. Check for existing agent-orchestrator.yaml
4. Auto-generate config if none exists
5. Start orchestrator and dashboard

The cloned repository will be placed in a directory named after the repo (e.g., ./repo).

Clone Authentication

The CLI attempts multiple authentication methods:

1. GitHub CLI (gh repo clone) - Uses your gh auth token
2. SSH (git clone [e-mail]:...) - Uses your SSH keys
3. HTTPS (git clone https://github.com/...) - Works for public repos

For private repositories, authenticate with GitHub CLI first:

gh auth login

Port Selection

The dashboard port is read from your config (agent-orchestrator.yaml):

port: 3000

If the port is busy, you’ll see:

Error: Port 3000 is already in use

Solution: Stop the existing server or change the port in your config.

When using ao start <url>, the CLI auto-generates a config with a free port.

Orchestrator Session

The orchestrator agent runs in a tmux session named:

<sessionPrefix>-orchestrator

For example, if your project’s sessionPrefix is ao, the session is ao-orchestrator.

Attach to Orchestrator

tmux attach -t ao-orchestrator

If the orchestrator session already exists, ao start will skip creation and show a warning.

Output Example

$ ao start

Starting orchestrator for agent-orchestrator

✓ Dashboard starting on http://localhost:3000
  (Dashboard will be ready in a few seconds)

✓ Orchestrator session created

✓ Startup complete

Dashboard:    http://localhost:3000
Orchestrator: tmux attach -t ao-orchestrator
Config:       /Users/user/agent-orchestrator.yaml

The browser will automatically open to the orchestrator session page once the server is ready.

Dashboard-Only Mode

Start just the dashboard without the orchestrator agent:

ao start --no-orchestrator

Useful when:

• Orchestrator session is already running
• You only want to view existing sessions
• Testing dashboard changes

Orchestrator-Only Mode

Start just the orchestrator without the dashboard:

ao start --no-dashboard

Useful when:

• Dashboard is already running on the port
• You’re working in the terminal only
• Debugging agent behavior

ao stop

Stop the orchestrator agent and dashboard for a project.

Syntax

ao stop [project]

Arguments

project · string

Project ID from config (optional if only one project exists)

Basic Usage

# Stop with single project config
ao stop

# Stop specific project
ao stop my-project

What Gets Stopped

1. Orchestrator Session - The tmux session is killed via the session manager
2. Dashboard Server - All processes listening on the configured port are killed

The stop command kills all processes on the dashboard port, not just the dashboard. Make sure no other services are using that port.

Output Example

$ ao stop

Stopping orchestrator for agent-orchestrator

✓ Orchestrator session stopped
Dashboard stopped

✓ Orchestrator stopped

Session Not Running

If the orchestrator session doesn’t exist:

Orchestrator session "ao-orchestrator" is not running
Dashboard stopped

✓ Orchestrator stopped

Common Issues

No Config Found

No config found. Run:
  ao init

Solution: Create a configuration file first:

ao init

Multiple Projects

Multiple projects configured. Specify which one to start:
  ao start project-a
  ao start project-b

Solution: Provide the project ID as an argument:

ao start project-a

Port Already in Use

Error: Port 3000 is already in use

Solution: Stop the existing server or change the port:

# Stop existing server
ao stop

# Or change port in config
port: 3001

Dashboard Build Not Found

Error: Dashboard not built. Run: pnpm build

Solution: Build the dashboard:

cd packages/web
pnpm build

tmux Not Available

Error: tmux not found. Install it first:
  brew install tmux

Solution: Install tmux:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt-get install tmux

Examples

Standard Workflow

# Start orchestrator and dashboard
ao start

# ... work with sessions ...

# Stop everything when done
ao stop

Quick Onboarding

# Start from GitHub URL (clone + generate config + start)
ao start https://github.com/composio/agent-orchestrator

Dashboard Rebuild

# Clean Next.js cache and rebuild
ao start --rebuild

Attach to Orchestrator

# Start services
ao start

# Attach to orchestrator session
tmux attach -t ao-orchestrator

Exit Codes

• 0 - Success
• 1 - Error (config not found, port busy, tmux not available)

Next Steps

Spawn Sessions

Create agent sessions for your issues

Status

Monitor running sessions

Dashboard

Learn more about the web interface