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.

Local-account sign-in or invitation fails

• Managed local accounts are not the DEFAULT_USER / DEFAULT_PASSWORD demo login. Ask the Super Admin to create a local-account workspace and invite its first Workspace Admin; that admin manages later users and resets. No local-auth environment switch or email service enables this workflow.
• Enter your username or email and choose the intended workspace or role when prompted. Local accounts cannot sign in to an OIDC workspace. A generic invalid-credentials response can mean a wrong password, an unknown account, or an invited, disabled, or deleted account; do not infer account existence from it.
• An invitation must be accepted before sign-in. Invite/reset links last 24 hours, are single-use, and are invalidated by replacements or relevant account changes. Request a new link through the appropriate admin; Chorus does not email it automatically. After setting a password, sign in separately. Passwords require at least 8 characters and at most 72 UTF-8 bytes.
• After a password reset or account change, old local sessions may be rejected because their session version is stale. Disabled/deleted users and incompatible workspace modes are denied; a failure to read current account state does not grant access. Restore database connectivity instead of bypassing account checks.
• If a successful login immediately disappears, check the public origin, cookie policy, and persistent NEXTAUTH_SECRET shared by all replicas. Use COOKIE_SECURE=true with HTTPS; reserve false for trusted HTTP-only trials. Removing Default Auth variables does not disable managed local password login.

See authentication setup and operations. Never share a credential-link URL, token, password, cookie, or signing secret in diagnostics.

Sign-in returns 429 or limits differ between replicas

HTTP 429 with RATE_LIMITED means an authentication limit was reached. Wait for the Retry-After number of seconds before retrying; repeated retries are not a recovery procedure. Identity lookup allows 30 attempts per 60 seconds; local password login and invitation/reset acceptance each allow 10 per 60 seconds. With trusted proxy addresses, users sharing an address may share an action limit.

Check that every replica uses the same Redis configuration. A nonempty REDIS_URL wins over the host-based TLS configuration. With neither REDIS_URL nor REDIS_HOST, limits are process-local. During a Redis outage, per-process insurance counters preserve only local limits. Inspect auth-throttle and Redis logs for connection or command failures, including READONLY/OOM; a working SSE stream does not prove the separate authentication connection is healthy. Unexpected limiter backend errors can fail open, so keep edge limits in place. A Redis outage is not a deliberate fail-closed login policy.

Check AUTH_TRUST_PROXY and AUTH_TRUST_PROXY_HOPS against the actual enforced proxy chain, not an assumed client header. Missing or invalid trusted addresses leave identity limits active without an address bucket. Do not enable trust to suppress an error or permit direct access around the proxy. See shared authentication throttling for exact defaults, timeouts, and recovery boundaries. Collect timestamps and sanitized error codes, not credentials or raw request headers.

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.

A --chorus-only violation (Claude Code, Chorus 0.22.2 and later). If the details say --chorus-only is not being enforced by this Claude Code build and list tools that are still available, the daemon found tools outside the Chorus allowlist when the wake started. It killed the process tree and forwarded nothing further, so restricted wakes cannot run on that Claude Code build. The daemon’s own remedy is --yolo; switch to it only if you intend to give the agent its full toolset. Otherwise keep --chorus-only and try a different Claude Code version. See What --chorus-only enforces.

Known credentials in the error details are replaced with [redacted]. Other text is not redacted, so review it before sharing.

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.