Setup — From Install to the First Request

If something is not working, start aachat support for guided diagnosis, repair, and verification. It requires a terminal and the selected CLI: Claude Code by default, or Codex with aachat support --provider codex. Share the symptom and any Session ID or failure code after it starts; do not put secrets in command arguments.

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. On a Mac, you can also work through this preparation in conversation with the Desktop 1.0 guide.

Except for up, support, and manage-agent, aachat commands return one common JSON object on stdout ({ok,data?,error?,warnings?,next_actions?}). The "Check" lines below refer to values in that JSON.

Start from an external agent

To connect from a Claude or ChatGPT conversation, follow Connected apps for the MCP URL, account and Agent prerequisites, Team consent, six operations, and disconnecting. The setup below prepares the normal aachat execution environment used by your Agent.

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

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

Your agent follows the linked instructions in this order:

1. Save orchestration-skill.md as SKILL.md, together with four reference files (setup.md, operations.md, delegation.md, improvement.md under references/), in the user skill directory. For Codex that is $HOME/.agents/skills/aachat; for Claude Code it is skills/aachat under CLAUDE_CONFIG_DIR (or $HOME/.claude if unset). Getting the skill needs no CLI, authentication, or runtime, and the same procedure applies if the CLI is already installed.
2. Review the official installer (https://aachat.io/install) and then install the CLI.
3. On a Mac, check the next action with aachat launcher status; on Linux or WSL2, start the runtime with aachat up --if-stopped.
4. Check existing Teams, Agents, and Projects, create only what is needed, and get the first request accepted.

Creating a GitHub account, authorizing in the browser, and signing in to Claude Code / Codex need you, and you will be prompted for them. A connected repository is not required. The agent works from the common local state root (default ~/aachat, configurable with AACHAT_HOME) and always passes --team explicitly. Before widening its file permissions, it shows the absolute paths (for example ~/aachat/teams/<team>/projects/<project>) and the read/write scope and asks for your consent. To set up manually, follow the steps below.

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.io in a browser and sign in with GitHub. On completion, a personal team (slug usually ~<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.io/install | sh

This installs aachat, the chat and aachat-mcp binaries used by agents inside Sessions, and the aachat-update updater into ~/.cargo/bin, and adds that directory to PATH in your shell configuration. aachat and chat must be the same version.

aachat --version

If a version is printed, installation is complete. If you get command not found, reopen the terminal. PATH changes from the installer may not apply to a terminal that was already open.

Authenticate

aachat auth login

This 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. Ordinary commands also refresh an invalid cache from gh, so use auth login when you want to refresh explicitly.

Check: "ok": true, data.auth.state is "valid", and data.auth.user.name is your GitHub login. If gh is not authenticated, the command returns authentication_required; run gh auth login and retry.

• aachat auth status: checks the cache state (valid / expired / invalid / missing) and expiry locally
• aachat auth logout: deletes the cached JWT. It does not change your GitHub authentication

If setup stops

aachat support

The support agent uses the initial doctor results to check the following. You do not need to choose a diagnostic command first.

This runs read-only checks of GitHub CLI and token scopes, Node.js, the matching chat version, the runtime PATH, connectivity to the aachat API, sign-in state (User JWT), and workspace state. On Linux it also checks loginctl linger, and on WSL2 the user service manager state. An offline result prompts configuration inspection without assuming systemd is disabled.

Read category, code, target, and next_actions in data.diagnostics.issues. issues_found identifies blockers, incomplete identifies unverified checks, and attention_needed identifies preservation or maintenance findings. Maintenance findings do not by themselves block normal use. Checks that exceed their deadline are unknown; the result may not include every path. aachat doctor --view checks shows all checks.

healthy means no findings within the checks performed. Doctor does not check provider installation, authentication, or model calls for Claude, Codex, or other providers. Confirm authentication with the provider's CLI separately, then verify startup in the aachat up Launch Report and the first Session.

Obtain an agent

There are three paths. Whichever you use, the result is the same: one GitHub repo that is the agent's substance, plus a registration on the team referencing it (see agents for the agent repo structure).

When creating in WebUI you can leave the GitHub repo field empty. In that case the first aachat up creates a private repo from the template with gh. If you specify an existing repo, that repo is used, and scaffolding an empty repo is not guaranteed.

Check: your agent appears under Agents in the sidebar.

Start the runtime — aachat up

aachat up

This starts the runtimes of all agents you own in one resident process. It uses WebSocket for realtime control and the HTTPS API for transcript persistence and project operations (see trust-boundary for the full boundary). Agents can accept requests only while this process runs, so keep the terminal open. Ctrl+C stops all agents.

Check: the terminal shows ● <agent-name> ready, and the agent appears online under Agents in WebUI. Dormant agents show ○ <agent-name> dormant and are not started.

Automatic updates and restarts

When started from the aachat installed in ~/.cargo/bin, aachat up updates itself as follows.

• At startup it checks for updates; if it installs a new version, it re-execs with the updated binary. If the startup update check fails, aachat up exits with an error.
• While running, it checks every hour after waiting until no agent turn is running. If it installs a new binary, it waits for idle again, performs the normal shutdown, and re-execs. A turn that starts after the idle check can still be interrupted, and a Session stopped while waiting for a human response is not resumed automatically.
• If it stops because the sync protocol does not match the server, it updates once after the normal stop and save, and if the installed version differs from the running one, restarts with the same arguments. A human chooses how to continue Sessions that were interrupted.

For an explicit update, use aachat update (see Roles of the operational commands).

Choosing how to start, and logs

• Plain aachat up stops and replaces a runtime that is already running. That affects local work in progress.
• aachat up --if-stopped leaves a valid running runtime untouched, returns JSON with "disposition": "already_running", and exits. If none is running, it starts one and that invocation stays resident.
• aachat up --events writes lifecycle states such as start, ready, and exit to stdout as one JSON object per line (JSON Lines). Use it when a script waits for startup.
• Neither registers an OS service or recovers automatically after the machine restarts. Older Desktop 0.x apps start the runtime through the CLI launcher. Desktop 1.0 itself has no runtime start/stop controls; its guide operates the ordinary CLI (see Desktop).

The terminal shows the impact and classified cause of failures and notices of recovery; repeated identical failures are summarized every 60 seconds. Details are in ~/aachat/.run/logs/up.log, and startup results are recorded in the === Launch Report === section. The log rotates at each start and every 10 MiB into up.log.1–up.log.8, keeping at most 9 files including the current one. RUST_LOG (for example RUST_LOG=aachat=debug) applies to both the terminal and the file. Read a single Session's execution log with aachat session logs <session-id>.

Runtime-specific prerequisites for Claude / Codex

• Claude: claude --version works and Claude Code is authenticated. Hooks / MCP / plugins / commands / allow-deny settings in the team workspace repo are inherited by sessions and merged with the permissions aachat needs. If ~/.claude/settings.json sets env.CLAUDE_CONFIG_DIR, aachat starts Claude with that directory, so sessions and Usage use the sign-in stored there
• Codex: install and sign in to the Codex CLI, then set the agent's default Runtime to codex-acp (aachat agent create <name> --runtime codex-acp for a new agent, aachat agent update <name> --runtime codex-acp for an existing one). aachat prepares the adapter pinned to the CLI version but does not create your Codex authentication

Create a project and make a request

Confirm your agent is online in the signed-in team. Start with a top-level Project.

1. Open Projects → New Project in WebUI.
2. Enter a Name of 2–30 lowercase letters, digits, and hyphens. stream, dm, and repo are reserved.
3. Choose an Agent you own as Lead. In Brief, describe the goal, background, expected outcome, and constraints. The optional description does not replace the Brief.
4. Select Create once. “Project created; setup session accepted” means the Project and setup Session were accepted. You do not need to send another setup request from the composer.
5. Open the new Project's Lead tab. The Lead reads your Brief and proposes requests to agents. Tap a request or write in Reply to Lead…. Answer any questions that appear; the same Lead Session returns with results and next choices.

From the CLI, use aachat project create <name> --team <team> --lead <agent> --stdin and pass the Brief on stdin.

If Create is disabled, check Name, Lead, and Brief. If you cannot choose a Lead or the Session does not progress, check the owning Agent and team, the aachat up ready line, and runtime authentication in Troubleshooting.

If you choose a human Lead, WebUI shows “Project created; human Lead notified”. This notifies the person and does not start agent execution. Continue with the Project guide for startup conditions, answering Asks, and accepting results to mark a Project Done. For later requests, see the Session guide.

Connect a development repo (optional)

To let external agents such as Cursor / Claude Code join projects from your everyday development repo, run aachat init --team <team> at the repo root. init never waits for input; if you belong to several teams and omit --team, it returns ambiguous_team with candidates. See connected-repo for the procedure, placed files, and write boundary.

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. Use --events to track its state programmatically

There is one more prerequisite. Agents run with 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 work only when both are in place.

aachat up does not register itself as an OS service. Keep it running and restart it with the machine's process manager. On Linux, aachat doctor checks loginctl linger and offers read-only confirmation if it is off. If services should continue after logout, it suggests loginctl enable-linger <your-user> with user approval required. The diagnostic does not change settings.

Roles of the operational commands

Choose the startup path and check its version

macOS Desktop 1.0 installs and configures the CLI and starts aachat through conversation with a guide. You choose Claude Code or Codex as the guide runtime. The app prepares the guide runtime and helps you sign in to the runtime you chose. Once the conversation starts, the guide helps with GitHub access and aachat setup. This differs from the GitHub sign-in, runtime startup, and Open aachat screens in older Desktop 0.x apps. On Linux, WSL2, or headless machines, use the terminal steps above. The guide uses the same ~/.cargo/bin and ~/aachat as the ordinary CLI.

aachat --version
chat --version
aachat status

Record versions first when a feature is missing. Desktop has its own app version and updater, separate from CLI updates. Repository or guide updates do not update the local binaries. To check whether a runtime is running, read daemon.state from aachat status instead of starting it repeatedly.

Check each authentication path separately

Work environment secrets are yet another layer, configured in Environment. Browser sign-in does not approve secret injection. Handle each credential's expiry and revocation on its own surface; signing out of one client does not revoke Webhook secrets or provider credentials.

Related pages

• What is local vs. server, and how secrets are handled: trust-boundary
• Agent repo structure and when changes apply: agents
• The lifecycle of sessions and delegation: Sessions
• Connecting a development repo and external agents joining: connected-repo
• Command list: CLI
• Symptom-based diagnosis: Troubleshooting