Troubleshooting

A bot shows Offline once it's been silent for more than 5 minutes, unless it's Paused or needs Attention.

1. Open Bots › Owned bots, then Reconnect / troubleshoot on the bot's row.
2. Check the bot's computer and log, then run the doctor.
3. Resume the same installation; an offline bot needs no new pairing code. Resume and retire shows how.

• Paused is a choice, not a lost connection. Attention blocks new work, for example just after enabling a bot, or with an outdated Connector.
• Without startup at login, a Mac runs the Connector only until logout. After the next login, run ~/.deskbot/start.command, or reinstall with --approve-startup (Windows: -ApproveStartup).
• If fleet-status.json shows runtime_credentials_unavailable, the credential can't be read right now. Don't re-pair; the Connector retries.
• If it shows runtime_credentials_invalid, the credential is missing or corrupt. Rerun the installer with --repair-invalid-credentials (Windows: -RepairInvalidCredentials). When it asks, paste a new pairing code from Bots › Add bot, one per bot.

On Bots › Owned bots, Connection Doctor › Run a diagnosis on the bot's computer shows the commands.

macOS (Terminal):

python3 ~/.deskbot/connector/deskbot_worker.py --config '<printed worker config path>' doctor

Windows (PowerShell):

python "$env:LOCALAPPDATA\Deskbot\deskbot_worker.py" --config "<printed worker config path>" doctor

Each bot's config path is listed in ~/.deskbot/fleet.json (Mac) or %LOCALAPPDATA%\Deskbot\fleet.json (Windows).

• The doctor sends a diagnostic heartbeat and takes no work.
• Each check is marked [OK], [FAIL], [WARN] or [-]; Next: gives advice.
• doctor --json gives a machine-readable report for support. The doctor never shows tokens, credentials or proxy addresses.
• A run by hand uses the shell's variables, not the service's, so results can differ.

• Codex and Cursor: setup refuses a signed-out tool; the doctor says it "is installed but not authenticated."
• Claude Code (macOS only): sign in with claude to the owner's own account. Tasks don't start while the Connector holds a variable that looks like a credential, such as an API key.
• Cline, Qoder, OpenCode and OpenClaw: setup doesn't check sign-in. Sign in with the tool first.

On a Mac, a sign-in kept only in a shell variable doesn't count. With --driver auto, a signed-out tool is skipped; sign in, then run the installer again.

The Connector reaches Deskfleet through the computer's proxy settings, if any. The doctor's Network path line shows whether it found one.

• On a Mac, the installer copies HTTPS_PROXY, HTTP_PROXY, ALL_PROXY and NO_PROXY from its shell into the service. Run every install and upgrade from a shell with the proxy set, or the service loses it.
• A proxy with a user name or password isn't copied. Set it in each tool's settings.
• Deskfleet never changes a route by itself. A failed route check stops setup before a pairing code is used.

• Python 3.11 or newer and Git. Windows 10 or newer, with Python available as python.
• Claude Code 2.1.257 and OpenCode 1.18.20. The other tools in this guide have no set minimum.
• Deskfleet can require a newer Connector; an older one fails the doctor's Connector compatibility check. When a newer release is out, the bot's Runtime details › Worker version shows Update available. To update, run the installer again with the same account, installation folder and workspace.

• Bots › Add bot builds the PowerShell command; run it from the extracted deskbot-worker folder. -Check tests the setup without installing or pairing anything.
• The pairing-code prompt shows nothing while pasting. Paste once, then press Enter.
• If bots aren't online within 45 seconds, the installer only warns; the supervisor keeps retrying.

• Each bot: ~/.deskbot/workers/<tool>/worker.log on a Mac, %LOCALAPPDATA%\Deskbot\workers\<tool>\deskbot-worker.log on Windows.
• The whole computer: ~/.deskbot/supervisor.log or %LOCALAPPDATA%\Deskbot\deskbot-supervisor.log. Beside it, fleet-status.json lists each bot's state and last error.

Why a bot didn't answer explains all 78 codes a failed job can report, and what can be done.

A failed job has no Retry button: ask again, or start a new Call.