# Install and set up Orchestrator

> Orchestrator.inc (formerly Agent Orchestrator). Not the `orchestrator` npm package.

Orchestrator (https://orchestrator.inc) is an open-source desktop app plus a local `ao` CLI that runs a fleet of coding agents, each in its own Git worktree, and follows every pull request to merge. This page is a runbook for a coding agent asked to "install Orchestrator" or "set up Orchestrator for this repo". Run the steps in order. Stop and ask the user only at the steps marked **Human step**.

## 1. Install the app

The app bundles the `ao` CLI and runs the daemon that the CLI talks to. Pick the user's OS.

### macOS (Ventura or later)

With Homebrew (preferred; also links `ao` onto PATH):

```bash
brew install --cask agent-orchestrator
```

Without Homebrew, download the .dmg for the Mac's chip (`uname -m`: `arm64` = Apple silicon, `x86_64` = Intel):

- Apple silicon: https://github.com/OrchestratorInc/agent-orchestrator/releases/latest/download/Orchestrator-darwin-arm64.dmg
- Intel: https://github.com/OrchestratorInc/agent-orchestrator/releases/latest/download/Orchestrator-darwin-x64.dmg

```bash
DMG=$( [ "$(uname -m)" = x86_64 ] && echo Orchestrator-darwin-x64.dmg || echo Orchestrator-darwin-arm64.dmg )
curl -fL -o /tmp/Orchestrator.dmg "https://github.com/OrchestratorInc/agent-orchestrator/releases/latest/download/$DMG"
hdiutil attach /tmp/Orchestrator.dmg -nobrowse -mountpoint /tmp/orchestrator-dmg
cp -R "/tmp/orchestrator-dmg/Agent Orchestrator.app" /Applications/
hdiutil detach /tmp/orchestrator-dmg
```

Verify the signature before opening it: the first command must succeed, and `TeamIdentifier` must be `X9LNSP8MC2`. If either check fails, delete the app and stop:

```bash
codesign --verify --deep --strict "/Applications/Agent Orchestrator.app"
codesign -dv "/Applications/Agent Orchestrator.app" 2>&1 | grep TeamIdentifier
```

One-line installer (uses Homebrew when present, otherwise prints these steps; never prompts): `curl -fsSL https://orchestrator.inc/cli/install.sh | sh`

### Windows (x64)

```powershell
winget install OrchestratorInc.AgentOrchestrator
```

Or download and run the installer: https://github.com/OrchestratorInc/agent-orchestrator/releases/latest/download/agent-orchestrator-win32-x64.exe

### Linux (x64)

Pick one:

- Debian/Ubuntu: https://github.com/OrchestratorInc/agent-orchestrator/releases/latest/download/agent-orchestrator-linux-x64.deb, then `sudo apt install ./agent-orchestrator-linux-x64.deb`
- Fedora/RHEL: https://github.com/OrchestratorInc/agent-orchestrator/releases/latest/download/agent-orchestrator-linux-x64.rpm, then `sudo dnf install ./agent-orchestrator-linux-x64.rpm`
- AppImage: https://github.com/OrchestratorInc/agent-orchestrator/releases/latest/download/agent-orchestrator-linux-x64.AppImage, then `chmod +x` it and run it

Installing a .deb or .rpm needs sudo. If you cannot run sudo, hand that command to the user (**Human step**).

## 2. Find the `ao` CLI

Use `ao` if `command -v ao` finds it (Homebrew installs link it). Otherwise run the bundled binary by its full path; in the commands below, replace `ao` with that path.

- macOS: `"/Applications/Agent Orchestrator.app/Contents/Resources/daemon/ao"`
- Linux (.deb/.rpm): `daemon/ao` inside the app's `resources` folder. Find it with `dpkg -L agent-orchestrator | grep 'resources/daemon/ao$'` or `rpm -ql agent-orchestrator | grep 'resources/daemon/ao$'`.
- Windows: `daemon\ao.exe` inside the app's `resources` folder, under the install directory (per-user installs go under `%LOCALAPPDATA%\Programs`). Find it with `Get-ChildItem "$env:LOCALAPPDATA\Programs" -Recurse -Filter ao.exe -ErrorAction SilentlyContinue | Where-Object FullName -like '*resources\daemon\ao.exe'`.
- AppImage: the CLI is inside the image, and the app's Global ao command link is not available for AppImage installs. Install the .deb or .rpm instead when you need `ao` in a terminal.

Sessions that Orchestrator itself starts already have `ao` on PATH. A person can also link a global `ao` on macOS and on Linux .deb/.rpm installs (not the AppImage) from **Settings → General → Developer mode → Global ao command**.

## 3. Start the app once

The desktop app owns the daemon. Open it once (it keeps running in the background):

```bash
ao start
```

`ao start` opens the installed app (or downloads the latest release first) and exits. On macOS you can also open it by its full path, `open "/Applications/Agent Orchestrator.app"` (or `open ~/Applications/"Agent Orchestrator.app"` if it is installed there). Opening it by name can start a helper bundled inside the app instead. Then wait until the daemon reports `"state": "ready"`:

```bash
ao status --json
```

Its `executablePath` should point inside the app you installed (on macOS, under `/Applications/Agent Orchestrator.app` or `~/Applications/Agent Orchestrator.app`; for a .deb/.rpm, under the package's `resources` folder). An AppImage runs from a temporary `/tmp/.mount_…` folder that changes on every launch, so check it another way: take `port` from that output and run `curl -s http://localhost:<port>/healthz`; its `appImagePath` must be the AppImage file you started. If it points somewhere else, such as a developer build of the app that is already running, tell the user and ask them to quit that build before you continue.

`ao doctor` checks the local environment and should print no `FAIL` lines.

## 4. Check which coding agents are ready

```bash
ao agent ls --refresh
```

Pick an agent whose INSTALL column says `installed` and whose AUTH column says `authorized` or `configured (unverified)`. `configured (unverified)` means a sign-in exists that the check has not proven; it usually works, so try it. With `--json`, use the `installed` list and each entry's `authStatus` (`authorized` or `configured`); the `authorized` list holds only proven sign-ins and can be empty even when an agent works. Prefer the agent you are running as, if it is listed.

**Human step:** if no installed agent shows `authorized` or `configured`, or a spawn fails because the agent is not signed in, ask the user to sign in to one with its own login command, for example `claude` then `/login`, or `codex login`. Never type credentials for them. Then run `ao agent ls --refresh` again.

## 5. Register the repository

Use the absolute path of the repo the user asked about (ask if more than one is plausible):

```bash
ao project add --path /absolute/path/to/repo --worker-agent <agent-id> --orchestrator-agent <agent-id>
```

It prints `registered project <project-id> at <path>`. `ao project ls` lists projects.

A repository with no `origin` remote also needs a default branch, or sessions cannot start:

```bash
ao project set-config <project-id> --default-branch <branch>
```

## 6. Start work

Start a worker on the user's task (`--name` is required and shows in the sidebar; `--agent` is an alias of `--harness`):

```bash
ao spawn --project <project-id> --name "<short name>" --agent <agent-id> --prompt "<the user's task>"
```

Or start the project's orchestrator, which plans larger work and spawns workers itself:

```bash
ao spawn --project <project-id> --kind orchestrator --name "<short name>"
```

`ao session ls` lists sessions. Tell the user to open the project in the Orchestrator app to follow the work.

## Human steps

Only the user can do these. Ask, then wait:

- Sign in to a coding agent with its own login command (for example `<agent> login`), or under **Settings → Harness** in the app.
- Sign in to GitHub with `gh auth login`, so Orchestrator can open pull requests and follow CI.
- Approve any sudo, installer or OS security prompt.

## Troubleshooting

- `ao: command not found`: use the bundled path from step 2, or install with Homebrew on macOS.
- `Orchestrator daemon is not running — start it with ao start`: run `ao start` (step 3), then `ao status --json` until it reports `ready`.
- `ao version` reports 0.10 or older: that is the retired npm CLI. Remove it with `npm uninstall -g @aoagents/ao` and use the bundled CLI.
- macOS says the app is damaged or from an unidentified developer: verify the signature (step 1: `codesign --verify --deep --strict`, TeamIdentifier `X9LNSP8MC2`) and download the .dmg again from the link above.
- Sessions fail to start in a repo with no remote: set a default branch (step 5).
- `ao agent ls --refresh` shows no agent as `authorized` or `configured (unverified)`: see **Human steps**.
- More: https://docs.orchestrator.inc/installation/ and https://docs.orchestrator.inc/cli/

## Uninstall

- macOS (Homebrew): `brew uninstall --cask agent-orchestrator`. Adding `--zap` also removes the app's preferences and caches; it removes `~/.ao` only if that folder is empty.
- macOS (.dmg): quit the app and delete `/Applications/Agent Orchestrator.app`.
- Windows: `winget uninstall OrchestratorInc.AgentOrchestrator`, or **Settings → Apps**.
- Linux: `sudo apt remove agent-orchestrator` or `sudo dnf remove agent-orchestrator`; for the AppImage, delete the file.
- Orchestrator's data (projects, sessions, settings) lives in `~/.ao`. Delete it only if the user asks.

## Links

- [Download page](https://orchestrator.inc/download/)
- [All releases](https://github.com/OrchestratorInc/agent-orchestrator/releases/latest)
- [Installation guide](https://docs.orchestrator.inc/installation/)
- [CLI reference](https://docs.orchestrator.inc/cli/)
- [Agent instructions](https://orchestrator.inc/agents.md)
- [llms.txt](https://orchestrator.inc/llms.txt)
- [GitHub](https://github.com/OrchestratorInc/agent-orchestrator)
