Reconnect or repair
Most connection problems are one of three things: an expired token, a session that started before setup, or a machine that is simply off.
Start with one tool call
Ask the agent to call citizenai_list_accounts. A result, also an empty list, proves the connection. A 401 or a 404 means that the token does not reach CitizenAI.
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. |
A tool call returns 401 or 404 |
Token expired or was revoked | Send the setup link again, and reconnect the agent on the approval page. |
| Tools missing | The session started before setup | Start a new session of the agent. |
| Approval link says expired | Device codes are short-lived | Ask the agent to start the setup again for a fresh link. |
"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.
Cloud sign-in will not start
The cloud browser runs on Browser Use, not on your machine. If pairing is healthy but a sign-in does not begin, check your wallet balance and see Cloud sign-in.
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.