Skip to main content
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:
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)
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
Per-project configuration. See Projects for details.
Notification channel configurations. See Notifications for details.
Route notifications by priority level. See Notifications for details.
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:
SlotPurposeDefaultAlternatives
RuntimeWhere sessions executetmuxprocess, docker, kubernetes, ssh, e2b
AgentAI coding assistantclaude-codecodex, aider, goose, opencode
WorkspaceCode isolationworktreeclone, copy
TrackerIssue trackinggithublinear, jira
SCMSource control & PRgithubGitLab, Bitbucket (future)
NotifierNotificationsdesktopslack, composio, discord, webhook
TerminalHuman interactioniterm2web
LifecycleSession 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

Build docs developers (and LLMs) love

Get started for freeTalk to us