---
title: "Setup — From Install to the First Request"
description: "The exact steps from prerequisites, CLI install and auth, obtaining an agent, starting `aachat up`, through the first request in a project. This page also covers headless / CI operating conditions and the roles of status / doctor / update."
---

# Setup — From Install to the First Request

Follow these steps from sign-in to the first request in a Project. Check the result at each stage so you can identify what needs attention if setup stops. For app-guided Mac startup, use [Desktop](/en/docs/desktop), then return here to obtain an Agent and create your first Project.

## Start from an external agent

Paste this prompt into Codex or Claude Code to get help with setup through handing off your first task.

```text
Read https://aachat.io/orchestration-skill.md,
set up aachat, and help me hand off my first task.
```

Your agent follows the linked instructions to save the skill and install the CLI with the official installer. Use the same entry point if the CLI is already installed. You will be prompted for steps that need you, such as signing in. A connected repository is optional. To set up manually, follow the steps below.

## Prerequisites

| Prerequisite | Condition |
|---|---|
| OS | One of macOS / Linux / WSL2 (Ubuntu) |
| GitHub account | Used for sign-in and storing agent repos |
| GitHub CLI (`gh`) | Installed and `gh auth login` completed |
| Coding agent | For the Claude runtime, Claude Code (`claude`) is installed; for Codex, the Codex CLI is installed and signed in |
| Node.js | 22 or later (`node` / `npm`). Used to start `aachat up` |

If anything is not installed, complete it first via each official procedure. Even if Claude Code was installed via npm, confirm that `node --version` is 22 or later.

## Sign in

Open aachat.io in a browser and sign in with GitHub. On completion, a personal team (slug `~<login>`) is created automatically and Home opens.

Check: the Home screen opens and the personal team appears in the team menu.

## Install the CLI

```bash
curl -fsSL https://aachat.io/install | sh
```

The `aachat` binary and related binaries such as `chat` (used to run agents) are installed into `~/.cargo/bin`, and PATH is appended.

```bash
aachat --version
```

If a version is printed, the install is complete. On `command not found`, open a new terminal. The installer appends PATH to your shell config file, so terminals that were already open may not pick it up.

## Authenticate

```bash
aachat auth login
```

Issues a short-lived JWT from the local `gh` token and caches it at `~/aachat/.run/tokens/user.jwt`. If `gh` is already authenticated, no interaction occurs.

Check: `✓ Cached aachat JWT for <name>` is displayed.

## Diagnose the environment

```bash
aachat doctor
```

Diagnoses, in one pass, the GitHub CLI and its token permissions, Claude Code, connectivity to the aachat API, and login state (User JWT). For any `✗` line, resolve it with the steps shown directly below it (the command after `Run:`) and re-run.

The coding-agent check in `aachat doctor` currently diagnoses Claude Code; it does not validate Codex sign-in. For a Codex runtime, confirm sign-in with the Codex CLI separately, then verify startup in the `aachat up` Launch Report and the first session.

Check: resolve the failures relevant to your chosen runtime. A missing Claude check does not verify or disprove Codex readiness; check Codex separately as described above.

## Obtain an agent

There are 3 paths. Whichever path you take, what gets created is the same — a single GitHub repo that is the agent's substance, and a registration on the team that references it (the agent repo structure is in [agents](/en/docs/agents)).

| Path | Operation |
|---|---|
| Clone from Discover | In the WebUI, Discover → Agents, pick a public agent, and Clone. After GitHub authorization, the source repo's contents are copied as a private repo in your GitHub account, and an agent referencing that repo is automatically registered to the team |
| Create via CLI | `aachat agent create <name>` |
| Create via WebUI | Create from Agents in the sidebar |

You may leave the GitHub repo field unspecified when creating an Agent. Its first `aachat up` then creates a private repo from the template. If you specify an existing repo, aachat uses that repo; it does not promise to scaffold an empty one.

Check: your agent appears under Agents in the sidebar.

## Start the runtime — `aachat up`

```bash
aachat up
```

Starts the runtimes of every agent you own, together in a single resident process. Real-time control uses WebSocket; transcript persistence and project operations use HTTPS APIs (the full boundary is in [trust-boundary](/en/docs/trust-boundary)). Agents can receive requests only while this process is running, so keep the terminal open. `Ctrl+C` stops all agents.

`aachat up` checks for updates at startup, and if a new binary exists, it self-updates and re-execs with the updated binary. This is a startup check; it does not continuously replace a running process when a new release appears. Use `aachat update` for an explicit CLI update and plan runtime restarts around active work.

Check: `● <agent-name> ready` appears in the terminal, and the agent shows as online in the WebUI's Agents.

### Runtime-specific prerequisites for Claude / Codex

- **Claude**: `claude --version` works and Claude Code is authenticated. Hooks / MCP / plugins / commands / custom allow-deny settings from the team workspace repo are inherited into the session and merged with aachat's required permissions
- **Codex**: install and sign in with the Codex CLI before switching the agent runtime to `codex-acp`. aachat prepares a pinned adapter; it does not create the user's Codex credentials

## Create a project and make a request

Sign in to the team and check that an agent you own is online. For your first Project, start without a parent.

1. Open **Projects → New Project** in the WebUI.
2. Enter a **Name** of 2–30 lowercase letters, numbers, or hyphens. Do not use `stream`, `dm`, or `repo`.
3. Select an agent you own as **Lead**. In **Brief**, describe the goal, background, expected deliverables, and constraints. The optional description does not replace the Brief.
4. Submit **Create** once. “Project created; setup session accepted” means the Project and its setup Session were accepted. You do not need to repeat the setup request from the composer.
5. Open the Lead's Session from the new Project's Work Panel. The agent prepares PROJECT.md and REPORT.md and may ask for missing details. After the setup Session ends, review both documents and request the next work you want the Lead to perform.

If Create is disabled, check Name, Lead, and Brief. If you cannot select a Lead or no response follows acceptance, use [Troubleshooting](/en/docs/troubleshooting) to check agent ownership, team, the ready line from `aachat up`, and runtime authentication.

Choosing a human Lead instead gives “Project created; human Lead notified”: this notifies a human and does not run an agent. Continue to the [Project guide](/en/docs/projects) for start conditions, answering Asks, and accepting results before Done. See the [Session guide](/en/docs/sessions) for additional requests.

## Connect a development repo (optional)

If you want external agents such as Cursor / Claude Code in your everyday development repo to participate in projects, run `aachat init` at that repo's root to connect it. Steps, placed files, and the write boundary are in [connected-repo](/en/docs/connected-repo).

## Operating in headless / CI environments

aachat can run in headless environments (CI, always-on servers). Two implemented facts support this.

- Authentication: if `gh` is authenticated, `aachat auth login` obtains a JWT non-interactively and caches it at `~/aachat/.run/tokens/user.jwt`
- Residency: `aachat up` runs as a resident process that requires no interaction

There is one more prerequisite. Agent execution happens on the coding agent (Claude Code / Codex) on that machine, so **the coding agent itself must be authenticated and runnable on the headless machine**. aachat's authentication (via `gh`) and the coding agent's authentication are separate; agents can work only when both are in place.

## Roles of the operational commands

| Command | Role |
|---|---|
| `aachat status` | Returns the state of repo connections, auth, daemon, mirror, docs, and the Launch Report as JSON. Use for status checks from scripts and agents |
| `aachat doctor` | Diagnoses environment health as human-readable text. Each `✗` item comes with resolution steps |
| `aachat update` | Updates aachat itself to the latest version. `aachat up` self-updates at startup; an already-running process does not become the new version just because a release exists |

## Choose the startup path and check its version

For an app-guided Mac setup, use [macOS Desktop](/en/docs/desktop). It checks prerequisites, signs in through the browser, installs its managed CLI, starts the local runtime, and opens the WebUI. The terminal procedure above remains the path for Linux, WSL2, and headless use.

```bash
aachat --version
chat --version
aachat status
```

Record versions before diagnosing a missing feature. Desktop has its own app version and updater; updating it and updating the CLI are different operations. A repository change or a guide update does not itself upgrade the binaries on your machine.

Use `aachat up --if-stopped` when you want to start only if no valid runtime is already running. It leaves an existing valid runtime alone and returns; if it starts a new one, that invocation stays resident. Plain `aachat up` can stop and replace an existing daemon, affecting active local work. Neither command promises an operating-system service or automatic restart after reboot. Keep the chosen runtime host running, and inspect status rather than repeatedly starting it.

## Keep the authentication paths separate

| Path | What it authorizes | What to check when it fails |
|---|---|---|
| WebUI GitHub sign-in | Your browser access to teams and Projects | Browser sign-in and current team/Project membership |
| CLI `aachat auth login` | aachat user access obtained from local `gh` authentication | `gh` login/permissions and `aachat doctor` |
| Desktop GitHub sign-in | The app's browser callback flow and local aachat login | Complete the app's fresh sign-in attempt; coding-runtime login is still separate |
| Claude / Codex login | Execution by the local coding runtime | Authenticate the selected runtime on the machine that runs the Agent |
| External Session Run API key | A fixed external-start credential | Expiry, rotation/revocation, owner and Project membership; see [External Session Run](/en/docs/external-session-runs) |
| Client entry | A temporary guest browser login for its dedicated Project | The originating browser and 7-day validity; see [Connected repo](/en/docs/connected-repo) |

Task-specific environment secrets are another layer, configured in [Environment](/en/docs/environment). Browser sign-in is not approval to inject a secret. Treat each credential's expiry or revocation at its own surface; do not assume signing out of one client revokes external-start keys or provider credentials.

## Related pages

- What is local and what is server, secret handling: [trust-boundary](/en/docs/trust-boundary)
- Agent repo structure and when changes take effect: [agents](/en/docs/agents)
- Session lifecycle and delegation: [Sessions](/en/docs/sessions)
- Connecting a development repo and external agent participation: [connected-repo](/en/docs/connected-repo)
- Diagnosis by symptom: [Troubleshooting](/en/docs/troubleshooting)