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

```bash theme={null}
ao start [project]
```

### Arguments

<ParamField path="project" type="string" optional>
  Project ID from config, or a GitHub repository URL for quick onboarding
</ParamField>

<Note>
  If you have only one project configured, the project argument is optional.
</Note>

### Options

<ParamField path="--no-dashboard" type="flag">
  Skip starting the dashboard server
</ParamField>

<ParamField path="--no-orchestrator" type="flag">
  Skip starting the orchestrator agent session
</ParamField>

<ParamField path="--rebuild" type="flag">
  Clean and rebuild dashboard before starting (fixes cache issues)
</ParamField>

### Basic Usage

```bash theme={null}
# 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:

```bash theme={null}
# 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

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

### Clone Authentication

The CLI attempts multiple authentication methods:

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

<Tip>
  For private repositories, authenticate with GitHub CLI first:

  ```bash theme={null}
  gh auth login
  ```
</Tip>

### Port Selection

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

```yaml theme={null}
port: 3000
```

If the port is busy, you'll see:

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

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

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

### Orchestrator Session

The orchestrator agent runs in a tmux session named:

```bash theme={null}
<sessionPrefix>-orchestrator
```

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

#### Attach to Orchestrator

```bash theme={null}
tmux attach -t ao-orchestrator
```

<Warning>
  If the orchestrator session already exists, `ao start` will skip creation and show a warning.
</Warning>

### Output Example

```bash theme={null}
$ 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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
ao stop [project]
```

### Arguments

<ParamField path="project" type="string" optional>
  Project ID from config (optional if only one project exists)
</ParamField>

### Basic Usage

```bash theme={null}
# 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

<Warning>
  The `stop` command kills **all** processes on the dashboard port, not just the dashboard. Make sure no other services are using that port.
</Warning>

### Output Example

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

Stopping orchestrator for agent-orchestrator

✓ Orchestrator session stopped
Dashboard stopped

✓ Orchestrator stopped
```

### Session Not Running

If the orchestrator session doesn't exist:

```bash theme={null}
Orchestrator session "ao-orchestrator" is not running
Dashboard stopped

✓ Orchestrator stopped
```

## Common Issues

### No Config Found

```bash theme={null}
No config found. Run:
  ao init
```

**Solution**: Create a configuration file first:

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

### Multiple Projects

```bash theme={null}
Multiple projects configured. Specify which one to start:
  ao start project-a
  ao start project-b
```

**Solution**: Provide the project ID as an argument:

```bash theme={null}
ao start project-a
```

### Port Already in Use

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

**Solution**: Stop the existing server or change the port:

```bash theme={null}
# Stop existing server
ao stop

# Or change port in config
port: 3001
```

### Dashboard Build Not Found

```bash theme={null}
Error: Dashboard not built. Run: pnpm build
```

**Solution**: Build the dashboard:

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

### tmux Not Available

```bash theme={null}
Error: tmux not found. Install it first:
  brew install tmux
```

**Solution**: Install tmux:

```bash theme={null}
# macOS
brew install tmux

# Ubuntu/Debian
sudo apt-get install tmux
```

## Examples

### Standard Workflow

```bash theme={null}
# Start orchestrator and dashboard
ao start

# ... work with sessions ...

# Stop everything when done
ao stop
```

### Quick Onboarding

```bash theme={null}
# Start from GitHub URL (clone + generate config + start)
ao start https://github.com/composio/agent-orchestrator
```

### Dashboard Rebuild

```bash theme={null}
# Clean Next.js cache and rebuild
ao start --rebuild
```

### Attach to Orchestrator

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Spawn Sessions" icon="rocket" href="/cli/spawn">
    Create agent sessions for your issues
  </Card>

  <Card title="Status" icon="chart-line" href="/cli/status">
    Monitor running sessions
  </Card>

  <Card title="Dashboard" icon="browser" href="/cli/dashboard">
    Learn more about the web interface
  </Card>
</CardGroup>


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