Configuration
Configure projects, agents, session interfaces, and local daemon behavior in current Orchestrator.
Orchestrator keeps its durable state under ~/.ao. The daemon stores projects, sessions, pull-request facts, notifications, and typed project configuration in SQLite under ~/.ao/data; ~/.ao/running.json lets the desktop app and CLI find the running daemon.
The desktop app is the normal place to add projects and change settings. The CLI talks to the same daemon API when you need a scriptable path.
Add a project
In the desktop app, choose Add project and select a local repository. From the CLI:
ao project add --path /absolute/path/to/repoTo set the default agents while registering the project:
ao project add --path /absolute/path/to/repo \
--worker-agent codex \
--orchestrator-agent claude-codeOrchestrator also supports workspace projects, which contain a root repository and direct child repositories:
ao project add --path /absolute/path/to/workspace --as-workspaceStandalone workers support projectless work: ao spawn --standalone --agent codex --name notes. Existing Scratch projects also use Orchestrator-managed directories without branches or PR claims.
Inspect and update configuration
ao project ls
ao project get <project-id>Use Project Settings in the desktop app for interactive changes. The CLI's set-config flags change only the fields they name, while --config-json replaces the entire project config. Before using it, read the CLI update warning. The CLI ignores unknown JSON keys.
Project configuration has typed fields for the base branch, session prefix, environment variables, symlinks, setup commands, worker and orchestrator agents, agent options, project rules, reviewers, automatic review, trusted repository URLs, issue intake, and container cleanup. The daemon API rejects unknown fields. The CLI's --config-json decoder ignores unknown keys, so a typo can clear existing settings when the full config is replaced.
See Projects for the current field reference.
Daemon environment
The primary daemon listener is always loopback-only and unauthenticated. Its bind host is not configurable. Useful environment variables include:
| Variable | Default | Purpose |
|---|---|---|
AO_PORT | 3001 | REST, events, terminal mux, health, and control port |
AO_DATA_DIR | ~/.ao/data | Durable daemon data |
AO_RUN_FILE | ~/.ao/running.json | Daemon discovery file |
AO_REQUEST_TIMEOUT | 60s | REST request timeout |
AO_SHUTDOWN_TIMEOUT | 10s | Graceful shutdown deadline. It also scales how long a starting daemon waits for a previous daemon to release the data directory (9 × this + 18 s) |
AO_ALLOWED_ORIGINS | packaged desktop origin | Additional trusted browser origins |
AO_TRACKER_INTAKE | off | Enables the issue-intake observer; a project's own trackerIntake cannot enable it alone |
Do not set HOST=0.0.0.0 or proxy the primary daemon to a network. For phone access, use the separate authenticated listener created by Connect Mobile. See Remote access.
Chat and Terminal UI defaults
Every session commits to one interface at a time:
- Chat uses a structured, runtime-less provider controller with durable messages, activities, approvals, and usage.
- Terminal UI runs the agent's native terminal interface through Orchestrator's terminal runtime.
Choose the default for new sessions in Settings → General. A choice made for a specific task takes precedence. If a requested interface is unavailable, Orchestrator uses Terminal UI as its compatibility fallback.
Project agentConfig.mode selects a provider execution mode. It does not select Chat or Terminal UI. Choose the interface in the new-session flow or with ao spawn --mode chat|tui. Compatible Claude Code and Codex sessions can switch interfaces without changing the Orchestrator session or worktree.
Manage recurring tasks in Automations, reusable project actions in Cues, installed provider readiness in Settings → Harness, and persistent profiles/imports in Settings → Browser. These features have their own settings/resources rather than legacy YAML keys.