Installation Guide

This guide covers the complete installation process for Agent Orchestrator, from prerequisites to verification.

Prerequisites

Required

Node.js 20+

Required for: Runtime environment for the orchestrator and CLIVerify your installation:

node --version  # Should be v20.0.0 or higher

Install or upgrade:

Download from nodejs.org

Or use nvm:

nvm install 20
nvm use 20
nvm alias default 20

Git 2.25+

Required for: Repository management and git worktreesVerify your installation:

git --version  # Should be 2.25.0 or higher

Why 2.25+? This version introduced improved worktree support that Agent Orchestrator relies on.Install or upgrade:

Download from git-scm.com
macOS: brew install git
Ubuntu/Debian: sudo apt install git

tmux (for default runtime)

Required for: Terminal multiplexing and session managementVerify your installation:

tmux -V  # Should print version

Install:

brew install tmux

If you plan to use a different runtime (Docker, Kubernetes, process), tmux is not required.

GitHub CLI (gh)

Required for: GitHub integration, PR creation, issue managementVerify your installation:

gh --version

Install:

brew install gh

Authenticate:

gh auth login

Select:

GitHub.com (not Enterprise)
HTTPS protocol (recommended)
Authenticate via browser
Include repo scope (full repository access)

Verify authentication:

gh auth status

Optional

Linear API Key (for Linear integration)

Required if: Using Linear for issue tracking

Get your API key from linear.app/settings/api

Set environment variable:

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

Verify:
```
echo $LINEAR_API_KEY
```

Slack Webhook (for Slack notifications)

Required if: Using Slack for notifications

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

Set environment variable:

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

Test the webhook:

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

Build from Source

Agent Orchestrator is not yet published to npm. Install by building from source. A published npm package is coming soon.

Clone the repository

git clone https://github.com/ComposioHQ/agent-orchestrator.git
cd agent-orchestrator

Run the setup script

The automated setup script handles all installation steps:

bash scripts/setup.sh

What the setup script does:

Validates prerequisites:
- Checks Node.js >= 20
- Checks Git >= 2.25
- Detects tmux installation
- Detects and validates GitHub CLI authentication
Offers interactive fixes (if running in a terminal):
- Install tmux via Homebrew (macOS)
- Authenticate GitHub CLI via gh auth login
Installs pnpm:
- Via corepack (preferred)
- Falls back to npm install -g pnpm if corepack fails
Installs dependencies:
```
pnpm install
```
Builds all packages:
```
pnpm build
```
Links CLI globally:
```
cd packages/cli && npm link
```

The script will exit with an error if required prerequisites (Node.js 20+, Git 2.25+) are not met. Install these first, then re-run the script.

Verify the installation

Check that the ao command is available:

ao --version

If the command is not found, the npm global bin directory may not be in your PATH. Add it to your shell profile:

export PATH="$(npm config get prefix)/bin:$PATH"

Then restart your terminal or run:

source ~/.zshrc  # or ~/.bashrc

Manual Installation (Alternative)

If you prefer to install manually without the setup script:

Install pnpm

npm install -g pnpm

Install dependencies

pnpm install

Build all packages

pnpm build

Link CLI globally

npm link -g packages/cli

Verify installation

ao --version

Configuration Setup

After installation, you need to create a configuration file. There are three methods:

Method 1: Quick Setup with `ao init --auto`

Auto-generate configuration with smart defaults:

cd ~/your-project
ao init --auto

This command:

Detects your git repository and remote
Identifies the default branch (main/master)
Detects project type (language, frameworks)
Generates agent rules based on detected project type
Creates agent-orchestrator.yaml with sensible defaults

Example output:

dataDir: ~/.agent-orchestrator
worktreeDir: ~/.worktrees
port: 3000
defaults:
  runtime: tmux
  agent: claude-code
  workspace: worktree
  notifiers: [desktop]
projects:
  my-app:
    repo: owner/my-app
    path: ~/my-app
    defaultBranch: main
    agentRules: |
      Always run tests before pushing.
      Use conventional commits (feat:, fix:, chore:).

Method 2: Interactive Wizard

Step through a guided setup:

cd ~/your-project
ao init

The wizard will prompt you for:

Data directory (default: ~/.agent-orchestrator)
Worktree directory (default: ~/.worktrees)
Dashboard port (default: 3000)
Runtime plugin (default: tmux)
Agent plugin (default: claude-code)
Workspace plugin (default: worktree)
Notifiers (default: desktop)
Project ID (short name for your project)
GitHub repo (format: owner/repo)
Local path (path to your repository)
Default branch (usually main or master)
Issue tracker (github, linear, or none)

The wizard auto-detects as much as possible from your current directory and environment variables.

Method 3: Manual Configuration

Copy and edit the example config:

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

Or start from a template in the examples/ directory:

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

Configuration File Breakdown

Here’s what a minimal configuration looks like:

# Where to store session metadata
dataDir: ~/.agent-orchestrator

# Where to create workspaces (git worktrees/clones)
worktreeDir: ~/.worktrees

# Web dashboard port
port: 3000

# Default plugins (these are the defaults — can be omitted)
defaults:
  runtime: tmux
  agent: claude-code
  workspace: worktree
  notifiers: [desktop]

# Projects (at minimum: repo and path)
projects:
  my-app:
    repo: owner/my-app
    path: ~/my-app
    defaultBranch: main
    sessionPrefix: app  # Optional: prefix for session IDs

Full Configuration Reference

See the complete configuration reference in agent-orchestrator.yaml.example with all available options:

Reactions: Auto-handle CI failures, review comments, auto-merge
Notification routing: Route by priority (urgent, action, warning, info)
Agent rules: Inline or file-based rules included in agent prompts
Per-project overrides: Override default plugins per project
Tracker configuration: Linear team IDs, custom trackers
Notifier configuration: Slack webhooks, custom webhooks
Symlinks and post-create commands: Copy files or run setup commands in workspaces

Example:

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

  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m      # Escalate after 30 minutes

  approved-and-green:
    auto: false             # Disabled by default
    action: auto-merge      # Merge when approved + CI passes
    priority: action

Verification Steps

After installation and configuration, verify everything is working:

Verify CLI is installed

ao --version

Should print the version number.

Verify configuration exists

ls agent-orchestrator.yaml

Should find the config file.

Verify GitHub authentication

gh auth status

Should show “Logged in to github.com”.

Verify tmux is available

tmux -V

Should print tmux version.

Start the orchestrator

ao start

Dashboard should open at http://localhost:3000 (or your configured port).

Integration Setup

GitHub Issues Integration

GitHub integration is enabled by default if you have the GitHub CLI authenticated. Authentication:

gh auth login

Required scopes:

repo — Full repository access (read/write code, issues, PRs)
read:org — Read organization membership (optional, for team mentions)

Verification:

gh auth status
gh repo view owner/repo  # Test API access

Linear Integration

Get API key

Visit linear.app/settings/api and create a new API key.

Set environment variable

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

Find your team ID

Your team ID is visible in the Linear workspace URL or via the API. You’ll need this for the config.

Configure in agent-orchestrator.yaml

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

Verify

echo $LINEAR_API_KEY  # Should print your key

Slack Integration

Create incoming webhook

Follow the Slack guide: api.slack.com/messaging/webhooks

Set environment variable

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

Configure in agent-orchestrator.yaml

defaults:
  notifiers: [desktop, slack]

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

Test the webhook

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

Troubleshooting

'ao' command not found after installation

Problem: The CLI is linked but not in your PATH.Solution:

# Add npm global bin to PATH
export PATH="$(npm config get prefix)/bin:$PATH"

# Add to shell profile (make it permanent)
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc

# Reload shell
source ~/.zshrc

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/

'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 default 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 via browser
# - Include repo scope

Verify:

gh auth status

Port 3000 already in use

Problem: Another service is using the dashboard port.Solution:Option 1: Change the port in agent-orchestrator.yaml:

port: 3001

Option 2: Kill the process using port 3000:

lsof -ti:3000 | xargs kill

When running multiple orchestrator instances, each needs a different port value.

YAML parse error

Problem: Syntax error in agent-orchestrator.yaml.Common issues:

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

Solution: Validate YAML syntax at yamllint.com

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

Permission denied during git operations

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

Next Steps

Now that Agent Orchestrator is installed and configured:

Quickstart

Spawn your first agent in 5 minutes

Configuration

Customize reactions, plugins, and routing

CLI Reference

Complete command reference

Troubleshooting

Common issues and solutions

Get Started

Core Concepts

Configuration

Guides

Installation

Installation Guide

Prerequisites

Required

Optional

Build from Source

Manual Installation (Alternative)

Configuration Setup

Method 1: Quick Setup with `ao init --auto`

Method 2: Interactive Wizard

Method 3: Manual Configuration

Configuration File Breakdown

Verification Steps

Integration Setup

GitHub Issues Integration

Linear Integration

Slack Integration

Troubleshooting

Next Steps

Quickstart

Configuration

CLI Reference

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Guides

Documentation Index

​Installation Guide

​Prerequisites

​Required

​Optional

​Build from Source

​Manual Installation (Alternative)

​Configuration Setup

​Method 1: Quick Setup with ao init --auto

​Method 2: Interactive Wizard

​Method 3: Manual Configuration

​Configuration File Breakdown

​Verification Steps

​Integration Setup

​GitHub Issues Integration

​Linear Integration

​Slack Integration

​Troubleshooting

​Next Steps

Quickstart

Configuration

CLI Reference

Troubleshooting

Build docs developers (and LLMs) love

Installation Guide

Prerequisites

Required

Optional

Build from Source

Manual Installation (Alternative)

Configuration Setup

Method 1: Quick Setup with `ao init --auto`

Method 2: Interactive Wizard

Method 3: Manual Configuration

Configuration File Breakdown

Verification Steps

Integration Setup

GitHub Issues Integration

Linear Integration

Slack Integration

Troubleshooting

Next Steps