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, then return here to obtain an Agent and create your first Project.

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.

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

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

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). 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; Lead work accepted” means the Project was created and the Lead's first work was accepted. You do not need to send the same request again from the composer.
5. Open the Lead's Session from the new Project's Work Panel and check the request and first response. Acceptance alone does not mean a deliverable is ready.

If Create is disabled, check Name, Lead, and Brief. If you cannot select a Lead or no response follows acceptance, use 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 for start conditions, answering Asks, and accepting results before Done. See the Session guide 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.

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

Choose the startup path and check its version

For an app-guided Mac setup, use macOS 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.

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

Task-specific environment secrets are another layer, configured in 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
• Agent repo structure and when changes take effect: agents
• Session lifecycle and delegation: Sessions
• Connecting a development repo and external agent participation: connected-repo
• Diagnosis by symptom: Troubleshooting