Installation
Download the Orchestrator desktop app and connect your coding tools.
For the latest stable desktop build, start at the official Orchestrator download page. It also lists nightly builds and the mobile apps. If you want a direct desktop package, choose one below:
| Platform | Download |
|---|---|
| macOS Apple silicon | |
| macOS Intel | |
| Windows x64 | |
| Linux x64 |
On your phone, install Orchestrator Mobile for iPhone or iPad or Orchestrator Mobile for Android. Then use Connect Mobile in the desktop app to pair it.
The desktop app is the canonical install path. It owns the local daemon, requires no global ao command, and checks for updates after launch and while it is running.
Optional macOS install with Homebrew
The desktop download above is the recommended install. On macOS, you can also install the existing Homebrew cask:
brew install --cask agentwrapper/tap/agent-orchestratorThe desktop app normally updates itself. To refresh a Homebrew-managed install, update Homebrew and then upgrade the cask:
brew update
brew upgrade --cask agentwrapper/tap/agent-orchestratorPrerequisites
| Tool | When you need it | Why |
|---|---|---|
| Git | Repository projects | Creates and manages isolated worktrees and branches. |
GitHub CLI gh | GitHub projects | Uses your existing authentication for repository and pull-request operations. |
| External coding agent (called a harness in Orchestrator) | Agent sessions that use an installed CLI | Install a supported tool such as Claude Code, Codex, Cursor, Aider, or OpenCode. See the agent catalog for the current list and interface support. Unreal Agent is built into Orchestrator for Chat on macOS and Linux. |
| tmux | macOS preflight and legacy/fallback terminal sessions | Desktop macOS/Linux packages include it. Source launches may need system tmux; see Runtime. |
Orchestrator uses the coding agents and sign-ins already installed on your computer. Settings → Harness offers setup and readiness checks for supported agents; some need to be installed or signed in outside Orchestrator. Unreal Agent is a built-in Chat-only exception with its own platform and permission limits. See the agent catalog.
Set up Orchestrator
Install and open the desktop app
Choose the download for your platform above, install it, and open Orchestrator. The app starts and supervises the local Go daemon automatically.
Authenticate GitHub
For a GitHub repository, install GitHub CLI if needed, then sign in:
gh auth login
gh auth statusUse an account that can read the repository and perform the branch and pull-request actions you expect the agent to take.
For GitLab, sign in with a GitLab token or glab. See source-control setup.
Install and sign in to an external agent
For an externally installed harness, install it and run it once outside Orchestrator to complete its sign-in flow. Orchestrator detects available harnesses when you create a session. If you use the built-in Unreal Agent, skip this step and choose it for a Chat session on supported macOS or Linux.
Chat support depends on the harness and installed version; see the agent capability catalog.
Add a project
In the desktop app, choose Add project and select an existing local Git repository. Orchestrator registers it without moving your original checkout. Each worker session gets its own isolated worktree.
You can also start a projectless standalone task for work that needs no repository. The optional CLI form is ao spawn --standalone --agent codex --name notes --prompt "Draft release notes"; standalone workers cannot claim a PR or take Git/project flags.
Legacy npm CLI
Already have the npm CLI?@aoagents/ao is frozen at 0.10.0 and is no longer recommended.
0.10.0 is the final npm release. The package remains a legacy bridge for existing users and will not receive new product features. Running ao start from that install fetches and opens the desktop build.
npm install -g @aoagents/ao
ao startNew users should install the desktop app directly instead.
Where Orchestrator stores data
All Orchestrator application state lives under ~/.ao by default, including the daemon database, run file, managed worktrees, Electron browser data, and mobile pairing configuration. Advanced installations can override daemon paths with AO_DATA_DIR and AO_RUN_FILE.
Common installation problems
No agent is available
For an external harness, install it, run it once to authenticate, then restart Orchestrator so the desktop-launched daemon receives the updated login-shell environment. Unreal Agent is built into Orchestrator for Chat on supported macOS and Linux; choose it directly instead of installing a CLI.
GitHub data is missing
Run gh auth status. Confirm the active account can access the repository and its pull requests.
Terminal UI cannot start on macOS or Linux
Packaged builds include tmux. New sessions normally use native PTY hosts; macOS still checks tmux availability and older sessions may need it. See runtime diagnostics for source installs and fallback behavior.
The legacy `ao` command is not found
The desktop app does not require it. Only troubleshoot the package manager's global bin path if you intentionally use the frozen legacy CLI.
macOS says the developer cannot be verified
In Finder, right-click Orchestrator, choose Open, then choose Open again in the confirmation dialog. If macOS still blocks the app, run these diagnostics and include the output when opening an issue:
sw_vers
codesign -dvvv "/Applications/Agent Orchestrator.app"
spctl -a -t exec -vvv --ignore-cache --no-cache "/Applications/Agent Orchestrator.app"
log show --last 10m --predicate 'subsystem == "com.apple.syspolicy"'