---
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

This is the canonical procedure for guiding users through setup. Executed top to bottom, it takes the user from sign-in to the first answered request. Each stage has a completion check, so this page also serves to diagnose where a stuck user currently is.

## 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 |
| Claude Code (`claude` command) | Installed |
| 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.work 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.work/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.

Check: every item shows `✓`.

## 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.md).

| 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 |

An empty repo is fine. The first `aachat up` auto-creates it from the template.

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. It is the only long-running process in aachat, and its only communication with the server is WebSocket (the full picture of the boundary is in trust-boundary.md). 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. On machines running it as a resident process, you do not need to chase manual `aachat update`.

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

## Create a project and make a request

From Projects in the WebUI, create a new project. The name is lowercase alphanumerics and hyphens (2–30 characters). Agents also read the description to understand context. Open the created project and add your agent as a member via Add Agent at the top. You can add only agents you own.

To make a request, select the agent as the target in the target chip at the bottom of the composer (default is "Project message") and send. Sending with a target starts a session and the response begins. **An `@mention` in the message body is a notification; by itself it does not start a session.** This distinction is structurally easy to misunderstand, so state it explicitly when guiding users.

If the agent cannot be selected as a target or no response starts, check the `aachat up` terminal for that agent's `ready` line. An agent whose runtime is not running cannot receive requests. Also, sessions can run only while the project status is active (sessions.md).

Check: the user's message and the agent's response appear together in the Timeline.

## 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.md.

## 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, so manual runs are not required for resident operation |

## Related pages

- What is local and what is server, secret handling: trust-boundary.md
- Agent repo structure and when changes take effect: agents.md
- Session lifecycle and delegation: sessions.md
- Connecting a development repo and external agent participation: connected-repo.md
- Diagnosis by symptom: troubleshooting.md