Troubleshoot agent connections

Start with the symptom visible in Chorus. Run the daemon in the foreground while diagnosing whenever possible, because startup errors are easier to see there.

The agent never comes online

1. Run chorus agents to confirm the agent is configured on this machine (it lists each agent’s name, UUID, and backend; API keys are never printed).
2. Run chorus daemon in the intended working directory.
3. Confirm the selected backend CLI is installed and available on PATH.
4. If the credential is missing or wrong, run chorus agents add (or chorus login) with the correct Chorus URL and agent API key.
5. Open Settings → Agents and check for a new Online heartbeat.

An HTTP 401 usually means the key is invalid or revoked. An HTTP 403 means the credential is valid but lacks permission for the requested operation. Correct the credential or required permission instead of granting broad administrator access.

The service is stopped or keeps restarting

Run:

chorus daemon status
chorus daemon logs
chorus daemon restart

If the agent CLI is missing from the service’s PATH, fix the installation and run chorus daemon install again with the intended backend and working directories. On Linux, use the service generated by Chorus; do not combine it with detached -d mode.

Chorus shows the wrong working directory

Stop the daemon and start it with the intended path:

chorus daemon --cwd /path/to/your/project --chorus-only

For multiple projects, repeat --cwd. If you changed an installed service, reinstall it with the complete desired list. Then confirm every expected path appears under the connection in Settings → Agents.

Starting remote work does nothing

Check that:

• the selected connection is still Online;
• the project or task is not fixed to a different offline connection;
• the working directory is registered by the daemon;
• the agent has permission to read the item and perform the requested action.

Restore the fixed connection or explicitly choose a new target. Do not broaden filesystem access merely to make a missing target appear.

Interrupt or resume fails

Open the conversation and check that its current state allows the interrupt or resume you requested. The daemon that owns the session must be online. Resume always returns to the original connection and working directory.

If the process crashed, inspect partial filesystem changes before resuming. For the full recovery procedure, see Interrupt and resume a session.

A turn fails before the agent replies

Open the failed conversation turn and read Agent wake failed. Expand Show error details if offered; no reply does not mean no diagnostic was recorded. See failed-turn diagnostics before retrying.

If the Linux daemon goes offline after SSH logout or reboot, check chorus daemon status and the lingering setup. For Codex that still uses old credentials after setup, follow the safe App Server restart, not just chorus daemon restart.

Collect useful diagnostics

Reproduce the problem once in restricted foreground mode:

chorus daemon --verbose --chorus-only --cwd /path/to/your/project

Record the failing step, time, backend, status message, and relevant log lines. Never share an API key. Remove private URLs, user names, repository paths, prompts, and command output that is unrelated to the problem.