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

# 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

<AccordionGroup>
  <Accordion title="Node.js 20+">
    **Required for**: Runtime environment for the orchestrator and CLI

    Verify your installation:

    ```bash theme={null}
    node --version  # Should be v20.0.0 or higher
    ```

    **Install or upgrade**:

    * Download from [nodejs.org](https://nodejs.org)
    * Or use nvm:
      ```bash theme={null}
      nvm install 20
      nvm use 20
      nvm alias default 20
      ```
  </Accordion>

  <Accordion title="Git 2.25+">
    **Required for**: Repository management and git worktrees

    Verify your installation:

    ```bash theme={null}
    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](https://git-scm.com/downloads)
    * macOS: `brew install git`
    * Ubuntu/Debian: `sudo apt install git`
  </Accordion>

  <Accordion title="tmux (for default runtime)">
    **Required for**: Terminal multiplexing and session management

    Verify your installation:

    ```bash theme={null}
    tmux -V  # Should print version
    ```

    **Install**:

    <CodeGroup>
      ```bash macOS theme={null}
      brew install tmux
      ```

      ```bash Ubuntu/Debian theme={null}
      sudo apt install tmux
      ```

      ```bash Fedora/RHEL theme={null}
      sudo dnf install tmux
      ```
    </CodeGroup>

    <Info>
      If you plan to use a different runtime (Docker, Kubernetes, process), tmux is not required.
    </Info>
  </Accordion>

  <Accordion title="GitHub CLI (gh)">
    **Required for**: GitHub integration, PR creation, issue management

    Verify your installation:

    ```bash theme={null}
    gh --version
    ```

    **Install**:

    <CodeGroup>
      ```bash macOS theme={null}
      brew install gh
      ```

      ```bash Linux theme={null}
      # See installation instructions:
      # https://github.com/cli/cli/blob/trunk/docs/install_linux.md
      ```
    </CodeGroup>

    **Authenticate**:

    ```bash theme={null}
    gh auth login
    ```

    Select:

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

    **Verify authentication**:

    ```bash theme={null}
    gh auth status
    ```
  </Accordion>
</AccordionGroup>

### Optional

<AccordionGroup>
  <Accordion title="Linear API Key (for Linear integration)">
    **Required if**: Using Linear for issue tracking

    1. Get your API key from [linear.app/settings/api](https://linear.app/settings/api)

    2. Set environment variable:

       ```bash theme={null}
       echo 'export LINEAR_API_KEY="lin_api_..."' >> ~/.zshrc
       source ~/.zshrc
       ```

    3. Verify:
       ```bash theme={null}
       echo $LINEAR_API_KEY
       ```
  </Accordion>

  <Accordion title="Slack Webhook (for Slack notifications)">
    **Required if**: Using Slack for notifications

    1. Create an incoming webhook: [api.slack.com/messaging/webhooks](https://api.slack.com/messaging/webhooks)

    2. Set environment variable:

       ```bash theme={null}
       echo 'export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."' >> ~/.zshrc
       source ~/.zshrc
       ```

    3. Test the webhook:
       ```bash theme={null}
       curl -X POST -H 'Content-type: application/json' \
         --data '{"text":"Agent Orchestrator test"}' \
         $SLACK_WEBHOOK_URL
       ```
  </Accordion>
</AccordionGroup>

## Build from Source

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

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/ComposioHQ/agent-orchestrator.git
    cd agent-orchestrator
    ```
  </Step>

  <Step title="Run the setup script">
    The automated setup script handles all installation steps:

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

    5. **Builds all packages**:
       ```bash theme={null}
       pnpm build
       ```

    6. **Links CLI globally**:
       ```bash theme={null}
       cd packages/cli && npm link
       ```

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Verify the installation">
    Check that the `ao` command is available:

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

    ```bash theme={null}
    export PATH="$(npm config get prefix)/bin:$PATH"
    ```

    Then restart your terminal or run:

    ```bash theme={null}
    source ~/.zshrc  # or ~/.bashrc
    ```
  </Step>
</Steps>

## Manual Installation (Alternative)

If you prefer to install manually without the setup script:

<Steps>
  <Step title="Install pnpm">
    ```bash theme={null}
    npm install -g pnpm
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm install
    ```
  </Step>

  <Step title="Build all packages">
    ```bash theme={null}
    pnpm build
    ```
  </Step>

  <Step title="Link CLI globally">
    ```bash theme={null}
    npm link -g packages/cli
    ```
  </Step>

  <Step title="Verify installation">
    ```bash theme={null}
    ao --version
    ```
  </Step>
</Steps>

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

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

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

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

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

### Method 3: Manual Configuration

Copy and edit the example config:

```bash theme={null}
cp agent-orchestrator.yaml.example agent-orchestrator.yaml
nano agent-orchestrator.yaml
```

Or start from a template in the `examples/` directory:

```bash theme={null}
cp examples/simple-github.yaml agent-orchestrator.yaml
nano agent-orchestrator.yaml
```

## Configuration File Breakdown

Here's what a minimal configuration looks like:

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

<Accordion title="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:

  ```yaml theme={null}
  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
  ```
</Accordion>

## Verification Steps

After installation and configuration, verify everything is working:

<Steps>
  <Step title="Verify CLI is installed">
    ```bash theme={null}
    ao --version
    ```

    Should print the version number.
  </Step>

  <Step title="Verify configuration exists">
    ```bash theme={null}
    ls agent-orchestrator.yaml
    ```

    Should find the config file.
  </Step>

  <Step title="Verify GitHub authentication">
    ```bash theme={null}
    gh auth status
    ```

    Should show "Logged in to github.com".
  </Step>

  <Step title="Verify tmux is available">
    ```bash theme={null}
    tmux -V
    ```

    Should print tmux version.
  </Step>

  <Step title="Start the orchestrator">
    ```bash theme={null}
    ao start
    ```

    Dashboard should open at `http://localhost:3000` (or your configured port).
  </Step>
</Steps>

## Integration Setup

### GitHub Issues Integration

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

**Authentication**:

```bash theme={null}
gh auth login
```

**Required scopes**:

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

**Verification**:

```bash theme={null}
gh auth status
gh repo view owner/repo  # Test API access
```

### Linear Integration

<Steps>
  <Step title="Get API key">
    Visit [linear.app/settings/api](https://linear.app/settings/api) and create a new API key.
  </Step>

  <Step title="Set environment variable">
    ```bash theme={null}
    echo 'export LINEAR_API_KEY="lin_api_..."' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="Configure in agent-orchestrator.yaml">
    ```yaml theme={null}
    projects:
      my-app:
        tracker:
          plugin: linear
          teamId: "your-team-id"
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    echo $LINEAR_API_KEY  # Should print your key
    ```
  </Step>
</Steps>

### Slack Integration

<Steps>
  <Step title="Create incoming webhook">
    Follow the Slack guide: [api.slack.com/messaging/webhooks](https://api.slack.com/messaging/webhooks)
  </Step>

  <Step title="Set environment variable">
    ```bash theme={null}
    echo 'export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Step>

  <Step title="Configure in agent-orchestrator.yaml">
    ```yaml theme={null}
    defaults:
      notifiers: [desktop, slack]

    notifiers:
      slack:
        plugin: slack
        webhook: ${SLACK_WEBHOOK_URL}
        channel: "#agent-updates"
    ```
  </Step>

  <Step title="Test the webhook">
    ```bash theme={null}
    curl -X POST -H 'Content-type: application/json' \
      --data '{"text":"Agent Orchestrator test"}' \
      $SLACK_WEBHOOK_URL
    ```
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="'ao' command not found after installation">
    **Problem**: The CLI is linked but not in your PATH.

    **Solution**:

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

  <Accordion title="Node version too old">
    **Problem**: Node.js version is below 20.

    **Solution**:

    ```bash theme={null}
    # Check version
    node --version

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

    # Or download from: https://nodejs.org/
    ```
  </Accordion>

  <Accordion title="'No agent-orchestrator.yaml found'">
    **Problem**: The orchestrator can't find your config file.

    **Solution**:

    ```bash theme={null}
    # Run init wizard
    ao init

    # Or copy an example
    cp examples/simple-github.yaml agent-orchestrator.yaml
    ```
  </Accordion>

  <Accordion title="'tmux not found'">
    **Problem**: tmux is not installed (required for default runtime).

    **Solution**:

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

    # Ubuntu/Debian
    sudo apt install tmux

    # Fedora/RHEL
    sudo dnf install tmux
    ```
  </Accordion>

  <Accordion title="'gh auth failed'">
    **Problem**: GitHub CLI is not authenticated.

    **Solution**:

    ```bash theme={null}
    gh auth login

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

    **Verify**:

    ```bash theme={null}
    gh auth status
    ```
  </Accordion>

  <Accordion title="Port 3000 already in use">
    **Problem**: Another service is using the dashboard port.

    **Solution**:

    **Option 1**: Change the port in `agent-orchestrator.yaml`:

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

    **Option 2**: Kill the process using port 3000:

    ```bash theme={null}
    lsof -ti:3000 | xargs kill
    ```

    <Note>
      When running multiple orchestrator instances, each needs a different `port` value.
    </Note>
  </Accordion>

  <Accordion title="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](https://www.yamllint.com/)
  </Accordion>

  <Accordion title="Workspace creation failed">
    **Problem**: Orchestrator can't create worktrees or clones.

    **Solution**:

    ```bash theme={null}
    # Check worktreeDir permissions
    ls -la ~/.worktrees

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

    # Check disk space
    df -h
    ```
  </Accordion>

  <Accordion title="Permission denied during git operations">
    **Problem**: Agent doesn't have permissions for git operations.

    **Solution**:

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

## Next Steps

Now that Agent Orchestrator is installed and configured:

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Spawn your first agent in 5 minutes
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Customize reactions, plugins, and routing
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Complete command reference
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/resources/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>


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