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

# Configuration Overview

> Learn how to configure Agent Orchestrator with agent-orchestrator.yaml

Agent Orchestrator is configured via a single YAML file that controls all aspects of the system—from project definitions to notification routing and reaction behaviors.

## Configuration File Location

The orchestrator searches for configuration in the following order:

<Steps>
  <Step title="Environment Variable">
    If `AO_CONFIG_PATH` is set, use that path:

    ```bash theme={null}
    export AO_CONFIG_PATH=/path/to/config.yaml
    ```
  </Step>

  <Step title="Directory Tree Search">
    Search up from current working directory (like git) for:

    * `agent-orchestrator.yaml`
    * `agent-orchestrator.yml`
  </Step>

  <Step title="Home Directory">
    Check standard locations:

    * `~/.agent-orchestrator.yaml`
    * `~/.agent-orchestrator.yml`
    * `~/.config/agent-orchestrator/config.yaml`
  </Step>
</Steps>

Source: `packages/core/src/config.ts:289-349`

## Creating Your First Config

The fastest way to get started:

```bash theme={null}
ao init
```

This launches an interactive wizard that detects your environment and generates a working configuration.

Alternatively, copy the example:

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

## Minimal Configuration

At minimum, you only need to define projects:

```yaml theme={null}
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    defaultBranch: main
```

Everything else has sensible defaults.

## Configuration Structure

The configuration file is organized into several top-level sections:

<Accordion title="Global Settings">
  System-wide settings that apply to all projects:

  <ParamField path="port" type="number" default="3000">
    Web dashboard port
  </ParamField>

  <ParamField path="terminalPort" type="number" default="14800">
    Terminal WebSocket server port (optional—auto-detected if not set)
  </ParamField>

  <ParamField path="directTerminalPort" type="number" default="14801">
    Direct terminal WebSocket port (optional)
  </ParamField>

  <ParamField path="readyThresholdMs" type="number" default="300000">
    Milliseconds before a "ready" session becomes "idle" (default: 5 minutes)
  </ParamField>
</Accordion>

<Accordion title="defaults">
  Default plugin selections for all projects (can be overridden per-project):

  <ParamField path="defaults.runtime" type="string" default="tmux">
    Where sessions execute: `tmux`, `process`, `docker`, `kubernetes`, `ssh`, `e2b`
  </ParamField>

  <ParamField path="defaults.agent" type="string" default="claude-code">
    AI coding assistant: `claude-code`, `codex`, `aider`, `goose`, `opencode`, `custom`
  </ParamField>

  <ParamField path="defaults.workspace" type="string" default="worktree">
    Workspace isolation: `worktree`, `clone`, `copy`
  </ParamField>

  <ParamField path="defaults.notifiers" type="array" default="['composio', 'desktop']">
    Notification channels
  </ParamField>
</Accordion>

<Accordion title="projects">
  Per-project configuration. See [Projects](/configuration/projects) for details.
</Accordion>

<Accordion title="notifiers">
  Notification channel configurations. See [Notifications](/configuration/notifications) for details.
</Accordion>

<Accordion title="notificationRouting">
  Route notifications by priority level. See [Notifications](/configuration/notifications) for details.
</Accordion>

<Accordion title="reactions">
  Auto-responses to events. See [Reactions](/configuration/reactions) for details.
</Accordion>

## Configuration Validation

Agent Orchestrator validates your configuration using Zod schemas at load time. If validation fails, you'll receive a detailed error message explaining what's wrong.

<Info>
  **Validation happens at startup**, so you'll know immediately if your configuration has issues.
</Info>

### Common Validation Errors

**Duplicate session prefixes:**

```
Duplicate session prefix detected: "app"
Projects "frontend" and "backend" would generate the same prefix.
```

**Solution:** Add explicit `sessionPrefix` to one project:

```yaml theme={null}
projects:
  frontend:
    sessionPrefix: fe
  backend:
    sessionPrefix: api
```

**Invalid session prefix format:**

```
sessionPrefix must match [a-zA-Z0-9_-]+
```

Session prefixes can only contain letters, numbers, underscores, and hyphens.

**Missing required fields:**

```yaml theme={null}
projects:
  my-app:
    repo: org/my-app  # ✓ Required
    path: ~/my-app    # ✓ Required
    # defaultBranch defaults to "main" if not specified
```

## Environment Variable Support

You can reference environment variables using `${VAR_NAME}` syntax:

```yaml theme={null}
notifiers:
  slack:
    plugin: slack
    webhook: ${SLACK_WEBHOOK_URL}
    channel: "#agent-updates"

projects:
  my-app:
    tracker:
      plugin: linear
      apiKey: ${LINEAR_API_KEY}
```

<Note>
  Environment variables are expanded when the config is loaded. Make sure to set them before running `ao start`.
</Note>

## Path Expansion

All path fields support `~` for home directory expansion:

```yaml theme={null}
projects:
  my-app:
    path: ~/projects/my-app  # Expands to /home/user/projects/my-app
```

Paths are automatically expanded when the configuration is loaded.

Source: `packages/core/src/config.ts:113-127`

## Plugin System

Agent Orchestrator has 8 plugin slots that control every aspect of the system:

| Slot | Purpose | Default | Alternatives |
| - | - | - | - |
| **Runtime** | Where sessions execute | `tmux` | `process`, `docker`, `kubernetes`, `ssh`, `e2b` |
| **Agent** | AI coding assistant | `claude-code` | `codex`, `aider`, `goose`, `opencode` |
| **Workspace** | Code isolation | `worktree` | `clone`, `copy` |
| **Tracker** | Issue tracking | `github` | `linear`, `jira` |
| **SCM** | Source control & PR | `github` | GitLab, Bitbucket (future) |
| **Notifier** | Notifications | `desktop` | `slack`, `composio`, `discord`, `webhook` |
| **Terminal** | Human interaction | `iterm2` | `web` |
| **Lifecycle** | Session management | (core) | Non-pluggable |

Each plugin implements a specific interface defined in `packages/core/src/types.ts`.

## Default Values

When you omit configuration, these defaults apply:

```yaml theme={null}
# Implied defaults (you don't need to write this)
port: 3000
readyThresholdMs: 300000  # 5 minutes

defaults:
  runtime: tmux
  agent: claude-code
  workspace: worktree
  notifiers: [composio, desktop]

notificationRouting:
  urgent: [desktop, composio]
  action: [desktop, composio]
  warning: [composio]
  info: [composio]

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 2
    escalateAfter: 2

  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m

  approved-and-green:
    auto: false
    action: notify
    priority: action

  agent-stuck:
    auto: true
    action: notify
    priority: urgent
    threshold: 10m
```

Source: `packages/core/src/config.ts:84-106,215-278`

## Configuration Reloading

<Warning>
  Configuration is loaded once at startup. Changes to `agent-orchestrator.yaml` require restarting the orchestrator to take effect.
</Warning>

To apply configuration changes:

1. Stop the orchestrator (Ctrl+C)
2. Edit `agent-orchestrator.yaml`
3. Restart: `ao start`

## Multiple Configurations

You can run multiple orchestrator instances with different configurations:

```bash theme={null}
# Terminal 1: Project A
cd ~/project-a
ao start  # Uses ./agent-orchestrator.yaml, port 3000

# Terminal 2: Project B
cd ~/project-b
ao start  # Uses ./agent-orchestrator.yaml, port 3001
```

<Info>
  Each orchestrator instance needs a unique `port` value to avoid conflicts.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Projects" icon="folder" href="/configuration/projects">
    Configure projects with repos, branches, and per-project settings
  </Card>

  <Card title="Reactions" icon="bolt" href="/configuration/reactions">
    Set up auto-responses to CI failures, reviews, and more
  </Card>

  <Card title="Notifications" icon="bell" href="/configuration/notifications">
    Route notifications to Slack, Discord, or custom webhooks
  </Card>
</CardGroup>


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