---
title: Configuration
description: How AO stores configuration, what belongs in the global registry, and what you should edit per project.
---

AO uses configuration in two layers:

- **Global registry** — remembers which projects AO knows about and which repository each project points to.
- **Local project config** — controls behavior for one project: agent, runtime, workspace, rules, reactions, tracker, SCM, and setup commands.

Most users should let `ao start` create the registry entry, then edit the local `agent-orchestrator.yaml` in the project when they want to change behavior.

<Callout type="info">
The old wrapped format with a top-level `projects:` block is still understood for compatibility, but new project-local configs should be flat. Do not put identity fields like `path`, `projectId`, `storageKey`, or `originUrl` in a local project config.
</Callout>

## What AO Creates

When you run AO in a repository, it can register the project globally and create a local config file:

```bash
ao start
```

The global registry lives at:

```text
~/.agent-orchestrator/config.yaml
```

That file is AO-owned. It stores durable identity:

```yaml title="~/.agent-orchestrator/config.yaml"
projects:
  my-app:
    projectId: my-app
    path: /Users/me/code/my-app
    storageKey: generated-by-ao
    repo:
      owner: acme
      name: my-app
      platform: github
      originUrl: git@github.com:acme/my-app.git
    defaultBranch: main
    sessionPrefix: app
```

The local project config lives inside the repository:

```text
my-app/agent-orchestrator.yaml
```

That file is for behavior:

```yaml title="agent-orchestrator.yaml"
agent: claude-code
runtime: tmux
workspace: worktree

symlinks:
  - .env
  - .claude

postCreate:
  - pnpm install

agentRules: |
  Run tests before pushing.
  Keep PRs small and focused.
```

## What To Edit

| Goal | Edit |
|------|------|
| Change the default agent or model | Local `agent-orchestrator.yaml` |
| Add `.env` or tool config files to each worktree | Local `symlinks` |
| Run setup commands before the agent starts | Local `postCreate` |
| Disable or tune automated recovery | Local or global `reactions` |
| Change notification routing for all projects | Global registry |
| Rename, remove, or relink a registered project | Use AO commands/dashboard project settings |
| Change where AO stores sessions | Do not hand-edit; re-register/relink if needed |

Do not manually edit `storageKey`, `path`, or `originUrl` unless you are repairing a broken registry entry and already know why it is wrong.

## Local Project Config

A practical local config usually starts with the agent, runtime, workspace, setup, and rules:

```yaml title="agent-orchestrator.yaml"
agent: claude-code       # claude-code | codex | aider | opencode
runtime: tmux            # tmux | process
workspace: worktree      # worktree | clone

agentConfig:
  permissions: permissionless
  model: claude-sonnet-4-5

symlinks:
  - .env

postCreate:
  - pnpm install

agentRules: |
  Use pnpm, not npm.
  Run pnpm test before opening a PR.
```

See [Projects](/docs/configuration/projects) for the full project behavior reference.

## Global Defaults

You can set defaults that apply across all registered projects in the global registry:

```yaml title="~/.agent-orchestrator/config.yaml"
defaults:
  agent: claude-code
  runtime: tmux
  workspace: worktree
  notifiers: [desktop]

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

Project-local values override global defaults.

## Config Lookup

AO resolves configuration in this order:

1. `AO_CONFIG_PATH`, if set.
2. `agent-orchestrator.yaml` or `agent-orchestrator.yml` found by walking upward from the current directory.
3. The global registry path.
4. Legacy home-directory fallbacks:
   - `~/.agent-orchestrator.yaml`
   - `~/.agent-orchestrator.yml`
   - `~/.config/agent-orchestrator/config.yaml`

For normal use, run AO from inside the repository and keep `agent-orchestrator.yaml` in the repo root.

## Top-Level Global Keys

| Key | Default | Purpose |
|-----|---------|---------|
| `port` | `3000` | Dashboard HTTP port |
| `terminalPort` | auto from `14800` | tmux terminal WebSocket port |
| `directTerminalPort` | auto from `14801` | direct PTY WebSocket port |
| `readyThresholdMs` | `300000` | Time before a ready session is treated as idle |
| `defaults` | built-ins | Cross-project defaults for agent/runtime/workspace/notifiers |
| `projects` | `{}` | Registered project identities |
| `projectOrder` | unset | Optional sidebar/project ordering |
| `notifiers` | `{}` | Named notifier instances |
| `notificationRouting` | desktop/composio defaults | Priority-to-notifier routing |
| `reactions` | built-in defaults | Global automation rules |

## Where Data Lives

AO stores runtime data under `~/.agent-orchestrator/` by storage key. Session files, archived sessions, feedback reports, and observability snapshots are plain files so they can be inspected during debugging.

You usually do not need to configure this. If you need to debug a session, start with:

```bash
ls ~/.agent-orchestrator
```

## Next Steps

<Cards>
  <Card title="Projects" href="/docs/configuration/projects" description="Per-project behavior settings: agents, workspaces, rules, setup, trackers, and SCM." />
  <Card title="Reactions" href="/docs/configuration/reactions" description="Control what AO does when CI fails, reviews arrive, or agents need help." />
  <Card title="Remote access" href="/docs/configuration/remote-access" description="Access the dashboard from another machine without exposing it publicly." />
</Cards>
