Troubleshoot Agentic Workers Supervisor

Start With Status and Doctor

agw-device status
agw-device doctor
agw-device logs

Pairing Expired or Wrong Workspace

Pairing lasts ten minutes. Run setup again for a new code if it expired or was already approved. Copy the command from the intended workspace and approve it as that workspace’s owner.

If the owner cannot approve, confirm Ultra is active for that workspace. Do not reuse another workspace’s install command or copy stored credentials between devices.

Environment Added but an Agent Is Missing or Not Ready

An environment may be connected while a profile is still being prepared or has failed. Check that the profile was selected at approval. Unselected profiles and profiles in other local accounts do not appear automatically.

Run doctor and inspect the logs. Resolve the reported ownership, path, version, permission, provider, or storage issue. Then run agw-device retry to retry failed profile setup on the next environment check.

If the workspace has no free Super Agent slots, select fewer profiles or free a slot. Adding a second device does not increase that allowance.

Another Installation or Gateway Owns This Profile

Do not delete a service or kill all Hermes processes to get past this message. Identify which account, profile, and service are already running. Keep unrelated profiles running.

Resolve ownership of the selected profile before retrying. If moving an existing managed environment to a different workspace, disconnect the old environment first, preserve local data, then copy the new workspace’s install command. This creates new cloud bindings; it is not a transfer of cloud chat history.

Device Offline, Sleeping, or Disk Locked

Check power, network access, disk availability, and the selected local account’s service. Linux sleep policy is unchanged. A locked encrypted disk or credentials tied to an interactive session can prevent operation before login.

The Supervisor reconnects after network recovery. If it remains offline, inspect logs and run doctor. Use restart only after reviewing active work, because restarting can interrupt runs for the environment’s agents.

Model Missing, Login Rejected, or Credits Exhausted

Check the selected agent’s payment mode and Configure, Provider & model. Provider access is per profile. A credential on another local profile does not make this profile authenticated.

For ChatGPT “connection needs attention”, use Reconnect ChatGPT and complete sign-in. For “could not verify”, restore connectivity and retry. If AGW credits are insufficient, the workspace billing owner must resolve the credit balance before retrying.

Do not switch providers just to hide an error. The Supervisor does not silently fall back to a cloud agent or an unsupported model.

Telegram Does Not Reply

Check the chosen Hermes profile’s Telegram bot token, allowed users, and gateway logs. Ensure another gateway is not polling the same bot. Do not paste the bot token into a support ticket.

A running Telegram gateway does not prove it has a destination for proactive messages. Configure the intended chat destination and test a direct reply before relying on scheduled delivery.

Update or Remove the Supervisor

Updates are explicit: run agw-device update <version> with a published version supplied by the release guidance. Failed activation attempts restore the prior executable. Review active work first; an update or restart can interrupt it.

Use agw-device disconnect to end the environment connection, or agw-device uninstall to also remove the managed service and command. Both preserve local agent data. If cloud revocation could not be confirmed, disconnect the environment from workspace settings too.

What to Send Support

Include the workspace name or ID, environment and agent IDs, operating system and architecture, agw-device version, status and doctor output, time of failure with time zone, and any affected run ID. Describe the steps and whether the profile was existing or new.

Share only the relevant log excerpt after removing secrets and private task content. Never send auth.json, environment-credentials.json, credentials.json, provider keys, bot tokens, pairing poll secrets, or a full environment file.