Skip to main content
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 [email protected]:...) - 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

Build docs developers (and LLMs) love

Get started for freeTalk to us