Reconnect or repair
Most connection problems are one of three things: an expired token, a runtime that was not restarted, or a machine that is simply off.
Start with status
This is the only authoritative check. What your agent says about its own connection is a guess; this is the state.
The common cases
| Symptom | Cause | Fix |
|---|---|---|
| Agent shows idle or offline in the dashboard | The runtime has not called CitizenAI for about a minute | Turn the host on and start the runtime. It reports in by itself; nothing needs re-pairing. |
status reports not paired |
Token expired or was revoked | Run citizenai pair again. |
| Tools missing in Hermes | Plugin loaded before enable, or app not restarted | Quit Hermes completely and relaunch. |
| Approval link says expired | Device codes are short-lived | Start citizenai pair again for a fresh link. |
| Pair command exits immediately | The previous run still holds the authorization | Wait for it to expire, then retry. |
"Offline" is usually not a fault
An agent is marked idle when it has not called CitizenAI for about a minute. A healthy paired agent with nothing to do looks exactly the same as one whose machine is switched off, so an idle badge on its own is not a problem to fix.
CitizenAI cannot wake a machine or start a runtime for you. Every connection is outbound, from your machine to CitizenAI, and no address on your side is stored — there is nothing to reach in through. Turn the host on, start the runtime, and it reports in on its next call. The pairing survives sleep, reboots, and network changes.
Re-pairing is safe
Pairing again does not delete accounts, does not revoke provisioned capabilities, and does not charge anything. It replaces the runtime's token. If you are unsure whether the connection is healthy, re-pair.
Live signup will not start
A signup needs the worker, a browser, and — on Linux — the display tooling. If pairing is healthy but signups never begin, check that the machine is awake and that the worker was installed by the same install that paired the runtime. See The signup worker.
When to remove instead
If a machine is gone for good, or you are moving an agent to new hardware, remove the agent rather than leaving a stale pairing behind. See Remove an agent.