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:

```sh
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:

```sh
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](/guides/session-recovery/).

## 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](/guides/session-recovery/#read-a-failed-turns-diagnostics) before retrying.

If the Linux daemon goes offline after SSH logout or reboot, check `chorus daemon status` and the [lingering setup](/guides/daemon-operations/#keep-the-linux-daemon-running-after-logout). For Codex that still uses old credentials after setup, follow the [safe App Server restart](/reference/agents/codex/#apply-configuration-to-an-existing-app-server), not just `chorus daemon restart`.

## Collect useful diagnostics

Reproduce the problem once in restricted foreground mode:

```sh
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.