Agent Orchestrator Setup Guide

Comprehensive guide to installing, configuring, and troubleshooting Agent Orchestrator.

Prerequisites

Required

Node.js 20+ - Runtime for the orchestrator and CLI
```
node --version  # Should be v20.0.0 or higher
```
Git 2.25+ - For repository management and worktrees
```
git --version
```
Terminal runtime — varies by OS:

On macOS / Linux: tmux is required (it's the default runtime).
```
tmux -V

# Install on macOS
brew install tmux

# Install on Ubuntu/Debian
sudo apt install tmux

# Install on Fedora/RHEL
sudo dnf install tmux
```
On Windows: tmux is not required. AO uses native ConPTY via the runtime-process plugin (the default on Windows). PowerShell 7+ is recommended; if you have Git Bash and prefer bash semantics for shell-out commands, set AO_SHELL=bash in your environment. WSL is not required.

GitHub CLI (for GitHub integration) - Required for PR creation, issue management

gh --version

# Install on macOS
brew install gh

# Install on Linux
# See: https://github.com/cli/cli/blob/trunk/docs/install_linux.md

Optional

Linear API Key - If using Linear for issue tracking
- Get it from: https://linear.app/settings/api
- Set environment variable: export LINEAR_API_KEY="lin_api_..."
Slack Webhook - If using Slack notifications
- Create incoming webhook: https://api.slack.com/messaging/webhooks
- Set environment variable: export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
Public dashboard URL - If running AO behind a reverse proxy (e.g. inside a remote dev container, on a VPS fronted by Caddy/nginx/Traefik)
- Set AO_PUBLIC_URL to the externally-reachable URL of the dashboard
- All console output, ao open browser launches, and orchestrator-prompt session links use this URL instead of http://localhost:<port>
- Example: export AO_PUBLIC_URL="https://ao.example.com"
- When the dashboard is served on a standard port (HTTPS 443 / HTTP 80) the dashboard JS connects the mux WebSocket to /ao-terminal-mux on the same hostname. Your proxy needs to forward that path to the direct terminal server (DIRECT_TERMINAL_PORT, default 14801) — its upgrade handler accepts both /mux and /ao-terminal-mux. For custom paths set TERMINAL_WS_PATH=/your/path.
- AO_PATH_BASED_MUX=1 (opt-in) — if your proxy can only forward one hostname:port pair (e.g. Cloudflare Tunnel pointed at a single service: URL with no path-based ingress), set this and ao start will run a small bundled HTTP/WS proxy on PORT that demultiplexes: HTTP forwards to Next.js (shifted to PORT + 1000, override with NEXT_INTERNAL_PORT), and wss://hostname/ao-terminal-mux is tunneled to DIRECT_TERMINAL_PORT/mux. Tradeoff: an extra Node process and one extra hop per HTTP request, in exchange for a one-line proxy config on the operator side.

Installation

Install via npm (recommended)

npm install -g @aoagents/ao

# Verify
ao --version

This installs the ao CLI globally along with all default plugins and the web dashboard.

Permission denied (EACCES)? This is common on macOS. Three options:

# Option 1: Use sudo
sudo npm install -g @aoagents/ao

# Option 2: Use npx (no global install needed)
npx @aoagents/ao start

# Option 3: Fix npm permissions permanently (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @aoagents/ao

Build from Source (for contributors)

If you want to develop or contribute to Agent Orchestrator:

# Clone the repository
git clone https://github.com/ComposioHQ/agent-orchestrator
cd agent-orchestrator

# Run the setup script (installs deps, builds, links CLI)
bash scripts/setup.sh

# Verify
ao --version

The setup script handles pnpm installation, dependency resolution, building all packages, and linking the ao command globally (with automatic permission handling on macOS).

First-Time Setup

`ao start` — the only command you need

ao start handles everything: auto-detecting your project, generating config, and launching the dashboard + orchestrator. There are three ways to use it:

From a URL (fastest for any repo):

ao start https://github.com/your-org/your-repo

This clones the repo, auto-detects language/framework/branch, generates agent-orchestrator.yaml, and starts everything. Supports GitHub, GitLab, and Bitbucket (HTTPS and SSH):

ao start https://github.com/owner/repo
ao start https://gitlab.com/org/project
ao start git@github.com:owner/repo.git

From a local repo (zero prompts):

cd ~/your-project
ao start

Auto-detects git remote, default branch, language, and available agent runtimes. Generates config and starts.

Adding more projects:

ao start ~/path/to/another-repo

If a config already exists, the new project is appended. If not, one is created first.

What `ao start` detects automatically

Git remote — parses owner/repo from origin
Default branch — checks symbolic-ref, GitHub API, then common names (main/master)
Project type — language, framework, test runner, package manager
Agent runtime — which AI agents are installed (Claude Code, Codex, Aider, OpenCode)
Free port — if configured port is busy, auto-finds the next available
tmux — warns if not installed (skipped on Windows; AO uses ConPTY there and tmux is not required)
GitHub CLI — checks gh auth status

Manual Configuration

If you prefer to write the config by hand:

cp agent-orchestrator.yaml.example agent-orchestrator.yaml
nano agent-orchestrator.yaml

Or start from an example:

cp examples/simple-github.yaml agent-orchestrator.yaml
nano agent-orchestrator.yaml

Configuration Reference

Minimal Configuration

The absolute minimum needed (everything else has sensible defaults):

projects:
  my-app:
    repo: owner/my-app
    path: ~/my-app
    defaultBranch: main

ao start generates this automatically — you only need to write it manually if you want full control.

Full Configuration Schema

See agent-orchestrator.yaml.example for a fully commented example with all options.

Plugin Slots

Agent Orchestrator has 8 plugin slots. All are swappable:

Slot	Purpose	Default	Alternatives
Runtime	How sessions run	`tmux` (macOS/Linux) / `process` (Windows; ConPTY via node-pty)	`process`, `docker`, `kubernetes`, `ssh`, `e2b`
Agent	AI coding assistant	`claude-code`	`codex`, `aider`, `goose`, custom
Workspace	Workspace isolation	`worktree`	`clone`, `copy`
Tracker	Issue tracking	`github`	`linear`, `jira`, custom
SCM	Source control	`github`	GitLab, Bitbucket (future)
Notifier	Notifications	`desktop`	`slack`, `discord`, `webhook`, `email`
Terminal	Terminal integration	`iterm2`	`web`, custom
Lifecycle	Session lifecycle	(core)	Non-pluggable

Reactions

Reactions are auto-responses to events. Configure how the orchestrator handles common scenarios:

CI Failed

reactions:
  ci-failed:
    auto: true # Enable auto-handling
    action: send-to-agent # Send failure logs to agent
    retries: 2 # Retry up to 2 times
    escalateAfter: 2 # Notify human after 2 failures

Changes Requested (Review Comments)

reactions:
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m # Notify human if not resolved in 30 minutes

Approved and Green (Auto-merge)

reactions:
  approved-and-green:
    auto: true # Enable auto-merge
    action: auto-merge # Merge when approved + CI passes
    priority: action # Notification priority

Warning: Only enable auto-merge if you trust your CI pipeline and agents!

Agent Stuck

reactions:
  agent-stuck:
    threshold: 10m # Consider stuck after 10 minutes of inactivity
    action: notify
    priority: urgent

Notification Routing

Route notifications by priority:

notificationRouting:
  urgent: [desktop, slack] # Agent stuck, needs input, errored
  action: [desktop, slack] # PR ready to merge
  warning: [slack] # Auto-fix failed
  info: [slack] # Summary, all done

Agent Rules

Inline rules included in every agent prompt:

projects:
  my-app:
    agentRules: |
      Always run tests before pushing.
      Use conventional commits (feat:, fix:, chore:).
      Link issue numbers in commit messages.

Or reference an external file:

projects:
  my-app:
    agentRulesFile: .agent-rules.md

Per-Project Overrides

Override defaults per project:

projects:
  frontend:
    runtime: tmux       # default on macOS/Linux; on Windows use `process`
    agent: claude-code
    workspace: worktree

  backend:
    runtime: docker # Use Docker for backend
    agent: codex # Use Codex instead of Claude

Integration Guides

GitHub Issues

Authentication:

gh auth login

Required scopes:

repo - Full repository access
read:org - Read organization membership (for team mentions)

Verification:

gh auth status

Linear

Setup:

Get your API key: https://linear.app/settings/api

Add to environment:

echo 'export LINEAR_API_KEY="lin_api_..."' >> ~/.zshrc
source ~/.zshrc

Find your team ID:
- Go to https://linear.app/settings/api
- Click "Create new key" or use existing key
- Team ID is visible in your Linear workspace URL or via API

Configure in agent-orchestrator.yaml:

projects:
  my-app:
    tracker:
      plugin: linear
      teamId: "your-team-id"

Branch names: On ao spawn <issue> with the Linear tracker, AO prefers Linear’s branch name (same as Copy git branch name, API field branchName). If that value is missing, it falls back to the previous convention: feat/<ISSUE-ID> (e.g. feat/INT-123). To change how Linear generates branchName, use Linear → Settings → Integrations → GitHub → Branch format.

Verification:

echo $LINEAR_API_KEY  # Should print your key

Slack

Setup:

Create incoming webhook: https://api.slack.com/messaging/webhooks

Add to environment:

echo 'export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."' >> ~/.zshrc
source ~/.zshrc

Configure in agent-orchestrator.yaml:

notifiers:
  slack:
    plugin: slack
    webhook: ${SLACK_WEBHOOK_URL}
    channel: "#agent-updates"

Verification:

# Send test message
curl -X POST -H 'Content-type: application/json' \
  --data '{"text":"Agent Orchestrator test"}' \
  $SLACK_WEBHOOK_URL

Custom Trackers

To add a custom tracker (Jira, Asana, etc.), create a plugin:

See plugin examples in packages/plugins/tracker-*/
Implement the Tracker interface from @aoagents/ao-core
Register your plugin in the config

See Development Guide for plugin development guidelines.

Troubleshooting

Run `ao doctor`

Use the built-in doctor before debugging a broken install by hand:

ao doctor
ao doctor --fix

ao doctor reports deterministic PASS/WARN/FAIL checks for PATH and launcher resolution, required binaries, terminal-runtime health (tmux on Unix; PowerShell / runtime-process on Windows), GitHub CLI health, stale AO temp files, config support directories, and core build/runtime sanity. It runs and is supported on Windows. --fix only applies safe fixes such as creating missing AO support directories, refreshing the local launcher link, and removing stale AO temp files.

Run `ao update`

When you installed AO from this repository and want to refresh that local install:

git switch main
ao update

ao update is intentionally conservative: it requires a clean working tree on main, fast-forwards from origin/main, reinstalls dependencies, clean-rebuilds the critical core/CLI/web packages, refreshes the launcher with npm link, and runs CLI smoke tests. Works on macOS, Linux, and Windows (Windows uses the bundled ao-update.ps1 script automatically). Use ao update --skip-smoke to stop after rebuild, or ao update --smoke-only to rerun just the smoke checks.

"No agent-orchestrator.yaml found"

Problem: The orchestrator can't find your config file.

Solution:

# ao start auto-creates the config if none exists
ao start

# Or copy an example and edit manually
cp examples/simple-github.yaml agent-orchestrator.yaml

"tmux not found"

Problem: tmux is not installed (required for the tmux runtime — the default on macOS and Linux).

Solution:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Fedora/RHEL
sudo dnf install tmux

On Windows: this error should not appear in normal use. If it does, your config has runtime: tmux set explicitly. Switch to runtime: process (or remove the override — process is the Windows default), and AO will use ConPTY natively without tmux.

"gh auth failed"

Problem: GitHub CLI is not authenticated.

Solution:

gh auth login

# Select:
# - GitHub.com (not Enterprise)
# - HTTPS (recommended)
# - Authenticate with browser
# - Include repo scope

Verify:

gh auth status

"LINEAR_API_KEY not found"

Problem: Linear API key is not set in environment.

Solution:

# Get your key from: https://linear.app/settings/api

# Add to shell profile
echo 'export LINEAR_API_KEY="lin_api_..."' >> ~/.zshrc
source ~/.zshrc

# Verify
echo $LINEAR_API_KEY

"Port already in use"

Problem: Another service is using the dashboard port (default 3000).

Note: ao start automatically finds the next free port if the configured port is busy. You'll see a message like "Port 3000 is busy — using 3001 instead." If you still need to fix it manually:

# Option 1: Change port in agent-orchestrator.yaml
port: 3001

# Option 2: Find and kill the process using the port
lsof -ti:3000 | xargs kill

"Workspace creation failed"

Problem: Orchestrator can't create worktrees or clones.

Solution:

# AO stores runtime data under ~/.agent-orchestrator/
ls -la ~/.agent-orchestrator

# Create the base directory if missing
mkdir -p ~/.agent-orchestrator

# Check disk space
df -h

"Session not found"

Problem: Session ID doesn't exist or was already destroyed.

Solution:

# List active sessions
ao session ls

# Check status dashboard
ao status

"Agent not responding"

Problem: Agent session is stuck or frozen.

Solution:

# Check session status
ao status

# Attach to session to investigate
ao open <session-name>

# Send message to agent
ao send <session-name> "Please report your current status"

# Kill and respawn if necessary
ao session kill <session-name>
ao spawn <issue-id>

"Permission denied" when spawning

Problem: Agent doesn't have permissions for git operations.

Solution:

# Check SSH keys are added
ssh -T git@github.com

# Add SSH key if needed
ssh-add ~/.ssh/id_ed25519

# Or use HTTPS and authenticate gh CLI
gh auth login

"YAML parse error"

Problem: Syntax error in agent-orchestrator.yaml.

Solution:

# Validate YAML syntax online: https://www.yamllint.com/

# Common issues:
# - Incorrect indentation (use 2 spaces, not tabs)
# - Missing quotes around strings with special characters
# - Typo in field names

"Node version too old"

Problem: Node.js version is below 20.

Solution:

# Check version
node --version

# Upgrade with nvm (recommended)
nvm install 20
nvm use 20
nvm alias default 20

# Or download from: https://nodejs.org/

Advanced Configuration

Multi-Project Setup

Manage multiple repositories:

projects:
  frontend:
    repo: org/frontend
    path: ~/frontend
    sessionPrefix: fe

  backend:
    repo: org/backend
    path: ~/backend
    sessionPrefix: api

  docs:
    repo: org/docs
    path: ~/docs
    sessionPrefix: doc

See examples/multi-project.yaml for full example.

Custom Plugin Development

Create custom plugins for:

Different runtimes (Docker, Kubernetes, SSH, cloud VMs)
Different agents (custom AI assistants)
Different trackers (Jira, Asana, custom systems)
Different notifiers (email, webhooks, custom integrations)

See Development Guide for plugin development guidelines.

Docker Runtime

Run agents in Docker containers:

defaults:
  runtime: docker

# Plugin will use official images or build from Dockerfile

Kubernetes Runtime

Run agents in Kubernetes pods:

defaults:
  runtime: kubernetes

# Requires kubectl configured with cluster access

Custom Notifiers

Send notifications to custom webhooks:

notifiers:
  webhook:
    plugin: webhook
    url: https://your-service.com/webhook
    method: POST
    headers:
      Authorization: "Bearer ${WEBHOOK_TOKEN}"

FAQ

What's a session?

A session is an isolated workspace where an agent works on a single issue. Each session has:

Its own git worktree or clone
Its own runtime session — a tmux session on macOS/Linux, a ConPTY pty-host process on Windows (or a Docker container, etc.)
Its own metadata (branch, PR, status)
Its own event log

Sessions are ephemeral — they're created for an issue and destroyed when merged.

What's a worktree vs clone?

Worktree (default):

Shares .git directory with main repo
Fast to create (no cloning)
Efficient disk usage
Best for local development

Clone:

Full independent repository clone
Slower to create
More disk space
Better for isolation, remote work

How do reactions work?

Reactions are event handlers that run automatically:

Event occurs (CI fails, review comment added, PR approved)
Orchestrator checks reaction config
If auto: true, performs the action automatically
If escalation threshold reached, notifies human

Actions can be:

send-to-agent - Forward event to agent to handle
auto-merge - Merge PR automatically
notify - Send notification to human

When should I enable auto-merge?

Enable auto-merge if:

✅ You have comprehensive CI/CD tests
✅ You require code review approval
✅ You trust your agents to write correct code
✅ You want maximum automation

Don't enable auto-merge if:

❌ You have incomplete test coverage
❌ You want manual review of every change
❌ You're still evaluating agent quality
❌ You work on critical systems (finance, healthcare, etc.)

Start with auto: false and enable after building confidence.

How do I add custom agent rules?

Inline:

projects:
  my-app:
    agentRules: |
      Always run tests before pushing.
      Use conventional commits.

External file:

projects:
  my-app:
    agentRulesFile: .agent-rules.md

Rules are included in every agent prompt for that project.

Can I use multiple trackers?

Yes! Different projects can use different trackers:

projects:
  frontend:
    tracker:
      plugin: github

  backend:
    tracker:
      plugin: linear
      teamId: "..."

How do I monitor agent progress?

Three ways:

Dashboard - ao start then visit http://localhost:3000 (or your configured port:)
CLI status - ao status (text-based dashboard)
Attach to session - ao open <session-name> (live terminal)

What if an agent gets stuck?

# Check status
ao status

# Send message
ao send <session-name> "What's your current status?"

# Attach to investigate
ao open <session-name>

# Kill and respawn if necessary
ao session kill <session-name>
ao spawn <issue-id>

Agents also send "stuck" notifications automatically after inactivity threshold.

How do I clean up old sessions?

# List all sessions
ao session ls

# Kill specific session
ao session kill <session-name>

# Cleanup script (example)
ao session ls --json --include-terminated | jq -r '.data[] | select(.status == "merged") | .id' | xargs -I{} ao session kill {}

Note: ao session ls --json and ao status --json emit { data: [...], meta: { hiddenTerminatedCount } }. By default terminated sessions (killed, terminated, done, merged, errored, cleanup) are hidden — pass --include-terminated to include them in data.

Can I run multiple orchestrators?

Yes! Each orchestrator instance should have:

Different dashboard port (port) — e.g., 3000 for project A, 3001 for project B
Different config location or project paths

AO derives runtime directories from the config location, so separate config locations already produce separate hash-scoped runtime paths under ~/.agent-orchestrator/. Terminal WebSocket ports are auto-detected by default, so you typically only need to set port: differently. If you need explicit control, you can also set terminalPort: and directTerminalPort: per config.

Useful for:

Separating projects
Different teams
Testing new configs

Next Steps

Start the orchestrator — ao start (auto-creates config on first run)
Spawn an agent — ao spawn 123 (project auto-detected from cwd)
Monitor progress — ao status or dashboard at http://localhost:3000
Read Development Guide — Code conventions and architecture
Explore examples — See examples/ for more configs
Join the community — Report issues, share configs, contribute plugins

Need help? Open an issue at: https://github.com/ComposioHQ/agent-orchestrator/issues

FilesExpand file tree

SETUP.md

Latest commit

History

SETUP.md

File metadata and controls

Agent Orchestrator Setup Guide

Prerequisites

Required

Optional

Installation

Install via npm (recommended)

Build from Source (for contributors)

First-Time Setup

ao start — the only command you need

What ao start detects automatically

Manual Configuration

Configuration Reference

Minimal Configuration

Full Configuration Schema

Plugin Slots

Reactions

CI Failed

Changes Requested (Review Comments)

Approved and Green (Auto-merge)

Agent Stuck

Notification Routing

Agent Rules

Per-Project Overrides

Integration Guides

GitHub Issues

Linear

Slack

Custom Trackers

Troubleshooting

Run ao doctor

Run ao update

"No agent-orchestrator.yaml found"

"tmux not found"

"gh auth failed"

"LINEAR_API_KEY not found"

"Port already in use"

"Workspace creation failed"

"Session not found"

"Agent not responding"

"Permission denied" when spawning

"YAML parse error"

"Node version too old"

Advanced Configuration

Multi-Project Setup

Custom Plugin Development

Docker Runtime

Kubernetes Runtime

Custom Notifiers

FAQ

What's a session?

What's a worktree vs clone?

How do reactions work?

When should I enable auto-merge?

How do I add custom agent rules?

Can I use multiple trackers?

How do I monitor agent progress?

What if an agent gets stuck?

How do I clean up old sessions?

Can I run multiple orchestrators?

Next Steps

`ao start` — the only command you need

What `ao start` detects automatically

Run `ao doctor`

Run `ao update`