19 KiB

Raw Blame History

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

tmux (for tmux runtime) - Terminal multiplexer for session management

tmux -V

# Install on macOS
brew install tmux

# Install on Ubuntu/Debian
sudo apt install tmux

# Install on Fedora/RHEL
sudo dnf install tmux

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/..."

Installation

Install via npm (recommended)

npm install -g @composio/agent-orchestrator

# 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 @composio/agent-orchestrator

# Option 2: Use npx (no global install needed)
npx @composio/agent-orchestrator 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 @composio/agent-orchestrator

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 Configuration

Quick Onboarding with `ao start <url>`

The fastest way to get started with any repo:

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

This single command will:

Clone the repo (or reuse an existing clone)
Auto-detect language, package manager, SCM platform, and default branch
Generate agent-orchestrator.yaml with smart defaults
Start the dashboard and orchestrator agent

Supports GitHub, GitLab, and Bitbucket URLs (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

If the repo already has an agent-orchestrator.yaml, it will be used as-is.

Quick Setup with `ao init`

For more control over configuration:

cd ~/your-repo
ao init

The wizard will prompt you for:

Data directory - Where to store session metadata (default: ~/.agent-orchestrator)
Worktree directory - Where to create isolated workspaces (default: ~/.worktrees)
Dashboard port - Web interface port (default: 3000)
Runtime plugin - Session runtime (default: tmux)
Agent plugin - AI coding assistant (default: claude-code)
Workspace plugin - Workspace isolation method (default: worktree)
Notifiers - Notification channels (default: desktop)
Project ID - Short name for your project
GitHub repo - Repository in owner/repo format
Local path - Path to your repository
Default branch - Main branch name (usually main or master)

What `ao init` Detects Automatically

The wizard is smart and tries to help:

Git repository - Detects if you're in a git repo
GitHub remote - Parses owner/repo from git remote
Current branch - Suggests default branch from git
API keys - Checks for LINEAR_API_KEY in environment
GitHub auth - Verifies gh CLI authentication status
tmux availability - Warns if tmux is not installed

Manual Configuration

If you prefer to write the config manually:

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:

dataDir: ~/.agent-orchestrator
worktreeDir: ~/.worktrees
port: 3000

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

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`	`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
    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"

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 @composio/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, tmux and GitHub CLI health, stale AO temp files, config support directories, and core build/runtime sanity. --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. 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:

# Run init wizard
ao init

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

"tmux not found"

Problem: tmux is not installed (required for tmux runtime).

Solution:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Fedora/RHEL
sudo dnf install 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).

Solution:

# 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

Note: When running multiple projects, each needs a different port: value in its config.

"Workspace creation failed"

Problem: Orchestrator can't create worktrees or clones.

Solution:

# Check worktreeDir permissions
ls -la ~/.worktrees

# Create directory if missing
mkdir -p ~/.worktrees

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

  mobile:
    repo: org/mobile
    path: ~/mobile
    sessionPrefix: mob

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 tmux session (or 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 <project-id> <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 | jq -r '.[] | select(.status == "merged") | .id' | xargs -I{} ao session kill {}

Can I run multiple orchestrators?

Yes! Each orchestrator instance should have:

Different data directory (dataDir)
Different dashboard port (port) — e.g., 3000 for project A, 3001 for project B
Different config file

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

Run ao init - Create your first config
Spawn an agent - ao spawn my-app ISSUE-123
Monitor progress - ao status or dashboard
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

19 KiB Raw Blame History

Agent Orchestrator Setup Guide

Prerequisites

Required

Optional

Installation

Install via npm (recommended)

Build from Source (for contributors)

First-Time Configuration

Quick Onboarding with ao start <url>

Quick Setup with ao init

What ao init 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

19 KiB

Raw Blame History

Quick Onboarding with `ao start <url>`

Quick Setup with `ao init`

What `ao init` Detects Automatically

Run `ao doctor`

Run `ao update`