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

1. Run chorus daemon in the intended working directory.
2. Confirm the selected backend CLI is installed and available on PATH.
3. Run chorus login again and enter the correct Chorus URL and agent API key.
4. 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 pinned 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 pinned 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 verify that it is currently in a state that allows the requested control. 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.

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.