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:

1. Environment Variable

   If AO_CONFIG_PATH is set, use that path:

   export AO_CONFIG_PATH=/path/to/config.yaml
   
2. Directory Tree Search

   Search up from current working directory (like git) for:

   • agent-orchestrator.yaml
   • agent-orchestrator.yml
3. Home Directory

   Check standard locations:

   • ~/.agent-orchestrator.yaml
   • ~/.agent-orchestrator.yml
   • ~/.config/agent-orchestrator/config.yaml

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

Creating Your First Config

The fastest way to get started:

ao init

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

Alternatively, copy the example:

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

Minimal Configuration

At minimum, you only need to define projects:

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:

Global Settings

System-wide settings that apply to all projects:

port · number · default: "3000"

Web dashboard port

terminalPort · number · default: "14800"

Terminal WebSocket server port (optional—auto-detected if not set)

directTerminalPort · number · default: "14801"

Direct terminal WebSocket port (optional)

readyThresholdMs · number · default: "300000"

Milliseconds before a “ready” session becomes “idle” (default: 5 minutes)

defaults

Default plugin selections for all projects (can be overridden per-project):

defaults.runtime · string · default: "tmux"

Where sessions execute: tmux, process, docker, kubernetes, ssh, e2b

defaults.agent · string · default: "claude-code"

AI coding assistant: claude-code, codex, aider, goose, opencode, custom

defaults.workspace · string · default: "worktree"

Workspace isolation: worktree, clone, copy

defaults.notifiers · array · default: "['composio', 'desktop']"

Notification channels

projects

Per-project configuration. See Projects for details.

notifiers

Notification channel configurations. See Notifications for details.

notificationRouting

Route notifications by priority level. See Notifications for details.

reactions

Auto-responses to events. See Reactions for details.

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.

Validation happens at startup, so you’ll know immediately if your configuration has issues.

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:

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:

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:

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

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

Environment variables are expanded when the config is loaded. Make sure to set them before running ao start.

Path Expansion

All path fields support ~ for home directory expansion:

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:

# 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

Configuration is loaded once at startup. Changes to agent-orchestrator.yaml require restarting the orchestrator to take effect.

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:

# 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

Each orchestrator instance needs a unique port value to avoid conflicts.

Next Steps

Projects

Configure projects with repos, branches, and per-project settings

Reactions

Set up auto-responses to CI failures, reviews, and more

Notifications

Route notifications to Slack, Discord, or custom webhooks