---
title: Installation
description: Install AO, authenticate the tools it controls, and verify your first project.
---

import { Callout } from "fumadocs-ui/components/callout";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Step, Steps } from "fumadocs-ui/components/steps";
import { Accordions, Accordion } from "fumadocs-ui/components/accordion";

This page gets your machine ready to run Agent Orchestrator. By the end, the `ao` command should be on your `PATH`, your source-control CLI should be authenticated, and `ao doctor` should be able to explain what is ready or missing.

<Callout type="info" title="What AO installs">
	The published package is `@aoagents/ao`. It provides the global `ao` command and includes the built-in CLI, dashboard,
	and plugin packages.
</Callout>

## Prerequisites

<PlatformSupport
	macos="full"
	linux="full"
	windows="partial"
	note={
		<>
			Windows support is actively improving. Use <code>defaults.runtime: process</code> instead of tmux. See{" "}
			<a href="/docs/platforms#windows">Platforms</a>.
		</>
	}
/>

Install these before running AO:

| Tool            | Required               | Why AO needs it                                                                      |
| --------------- | ---------------------- | ------------------------------------------------------------------------------------ |
| Node.js 20+     | Yes                    | Runs the AO CLI, dashboard, and plugins.                                             |
| Git             | Yes                    | Creates worktrees, branches, commits, and cleanup operations.                        |
| GitHub CLI `gh` | For GitHub projects    | Reads issues, PRs, reviews, and CI status as your user.                              |
| tmux            | Default on macOS/Linux | Keeps long-running agent sessions attachable and recoverable.                        |
| An agent CLI    | Yes                    | The worker that writes code, such as Claude Code, Codex, Cursor, Aider, or OpenCode. |

If you plan to use GitLab or Linear, install and authenticate their CLIs or credentials as described on the related plugin pages. A GitHub-only setup only needs `gh`.

## Install AO

<Tabs items={["npm", "pnpm", "yarn", "from source"]}>
	<Tab value="npm">```bash npm install -g @aoagents/ao ```</Tab>
	<Tab value="pnpm">```bash pnpm add -g @aoagents/ao ```</Tab>
	<Tab value="yarn">```bash yarn global add @aoagents/ao ```</Tab>
	<Tab value="from source">
		```bash git clone https://github.com/ComposioHQ/agent-orchestrator cd agent-orchestrator pnpm install pnpm build
		pnpm --filter @aoagents/ao link --global ```
	</Tab>
</Tabs>

Confirm the command is available:

```bash
ao --version
```

## Authenticate Your Tools

<Steps>
<Step>

### Authenticate source control

For GitHub projects, AO uses `gh` for issue lookup, PR discovery, reviews, CI checks, and merge readiness.

```bash
gh auth login
gh auth status
```

The authenticated account must be able to read the repository, create branches, push branches, open PRs, and read CI status.

</Step>
<Step>

### Install and sign in to one agent

AO launches an agent CLI inside each worker session. Start with the one you already use, then add more later if you want per-project or per-role choices.

<Tabs items={["Claude Code", "Codex", "Cursor", "Aider", "OpenCode"]}>
	<Tab value="Claude Code">```bash npm install -g @anthropic-ai/claude-code claude ```</Tab>
	<Tab value="Codex">```bash npm install -g @openai/codex codex ```</Tab>
	<Tab value="Cursor">```bash curl https://cursor.com/install -fsS | bash agent --help ```</Tab>
	<Tab value="Aider">```bash pip install aider-install aider-install aider --help ```</Tab>
	<Tab value="OpenCode">```bash npm install -g opencode-ai opencode --help ```</Tab>
</Tabs>

</Step>
<Step>

### Start AO in a repo

Run `ao start` from a repository you want AO to manage:

```bash
cd ~/code/my-repo
ao start
```

If there is no `agent-orchestrator.yaml`, AO creates one. It also starts the dashboard and an orchestrator session for the project.

You can also start from a path or clone from a URL:

```bash
ao start ~/code/my-repo
ao start https://github.com/your-org/your-repo
```

</Step>
<Step>

### Run the doctor check

```bash
ao doctor
```

`ao doctor` checks the launcher, config, plugin resolution, runtime tools, source-control authentication, notifier setup, and stale temporary files. If it reports a fixable issue, run:

```bash
ao doctor --fix
```

</Step>
</Steps>

## Windows Setup

Windows support is in progress. Use the process runtime instead of tmux:

```yaml title="agent-orchestrator.yaml"
defaults:
  runtime: process
```

Use Slack, Discord, webhook, or another network notifier for alerts. Desktop notifications and iTerm2 integration are not available on Windows.

## Common Install Issues

<Accordions>
	<Accordion title="`ao` is not found after install">
		Your global package bin directory is not on `PATH`. Check your package manager's global bin path, then reopen your
		shell and run `ao --version` again.
	</Accordion>
	<Accordion title="`gh` is not authenticated">
		Run `gh auth login`, then `gh auth status`. AO cannot read GitHub issues, PRs, reviews, or CI checks until `gh` is
		authenticated.
	</Accordion>
	<Accordion title="tmux is missing">
		Install tmux on macOS or Linux, or set `defaults.runtime: process` if you are on Windows or running in a container.
	</Accordion>
	<Accordion title="No agent runtime is detected">
		Install one supported agent CLI and run it once outside AO so it can complete its own sign-in flow.
	</Accordion>
	<Accordion title="Port 3000 is already in use">
		`ao start` scans for a free port and prints the final dashboard URL. Use the URL in the command output.
	</Accordion>
	<Accordion title="The dashboard fails after an update">
		Run `ao dashboard --rebuild` to clean stale dashboard build artifacts and start again.
	</Accordion>
</Accordions>

## Next

<Cards>
	<Card title="Quickstart" description="Run one worker session from start to pull request." href="/docs/quickstart" />
	<Card
		title="Configuration"
		description="Understand the generated `agent-orchestrator.yaml`."
		href="/docs/configuration"
	/>
	<Card title="Platforms" description="Choose the right runtime and notifier for your OS." href="/docs/platforms" />
</Cards>
