Installation

Complete installation guide for Agent Orchestrator with prerequisites and configuration

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 CLI

Verify 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 worktrees

Verify 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 management

Verify your installation:

tmux -V  # Should print version

Install:

macOS

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 management

Verify your installation:

gh --version

Install:

macOS

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

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

2. Set environment variable:

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

3. Verify:

   echo $LINEAR_API_KEY
   

Slack Webhook (for Slack notifications)

Required if: Using Slack for notifications

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

2. Set environment variable:

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

3. 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.

1. Clone the repository

   git clone https://github.com/ComposioHQ/agent-orchestrator.git
   cd agent-orchestrator
   
2. Run the setup script

   The automated setup script handles all installation steps:

   bash scripts/setup.sh
   

   What the setup script does:

   1. Validates prerequisites:

      • Checks Node.js >= 20
      • Checks Git >= 2.25
      • Detects tmux installation
      • Detects and validates GitHub CLI authentication

   2. Offers interactive fixes (if running in a terminal):

      • Install tmux via Homebrew (macOS)
      • Authenticate GitHub CLI via gh auth login

   3. Installs pnpm:

      • Via corepack (preferred)
      • Falls back to npm install -g pnpm if corepack fails

   4. Installs dependencies:

      pnpm install
      

   5. Builds all packages:

      pnpm build
      

   6. 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.

3. 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:

1. Install pnpm

   npm install -g pnpm
   
2. Install dependencies

   pnpm install
   
3. Build all packages

   pnpm build
   
4. Link CLI globally

   npm link -g packages/cli
   
5. 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:

1. Data directory (default: ~/.agent-orchestrator)
2. Worktree directory (default: ~/.worktrees)
3. Dashboard port (default: 3000)
4. Runtime plugin (default: tmux)
5. Agent plugin (default: claude-code)
6. Workspace plugin (default: worktree)
7. Notifiers (default: desktop)
8. Project ID (short name for your project)
9. GitHub repo (format: owner/repo)
10. Local path (path to your repository)
11. Default branch (usually main or master)
12. 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:

1. Verify CLI is installed

   ao --version
   

   Should print the version number.

2. Verify configuration exists

   ls agent-orchestrator.yaml
   

   Should find the config file.

3. Verify GitHub authentication

   gh auth status
   

   Should show “Logged in to github.com”.

4. Verify tmux is available

   tmux -V
   

   Should print tmux version.

5. 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

1. Get API key

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

2. Set environment variable

   echo 'export LINEAR_API_KEY="lin_api_..."' >> ~/.zshrc
   source ~/.zshrc
   
3. 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.

4. Configure in agent-orchestrator.yaml

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

   echo $LINEAR_API_KEY  # Should print your key
   

Slack Integration

1. Create incoming webhook

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

2. Set environment variable

   echo 'export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."' >> ~/.zshrc
   source ~/.zshrc
   
3. Configure in agent-orchestrator.yaml

   defaults:
     notifiers: [desktop, slack]
   
   notifiers:
     slack:
       plugin: slack
       webhook: ${SLACK_WEBHOOK_URL}
       channel: "#agent-updates"
   
4. 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 [e-mail]

# 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