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

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

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.

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

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

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

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

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

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