AI agent troubleshooting: the common fixes

Start with doctor

remoteagent doctor checks the install, the environment, and the connection to the control plane in one pass. Run it before guessing.

Agent shows offline

1. Run remoteagent status — is the daemon up?
2. Start it with remoteagent start.
3. Refresh the device link with remoteagent login.
4. Check the clock — a wrong time breaks token checks.

Shell command denied

The command is not in the allowlist, or it matches an always-blocked pattern. Open the agent’s Capabilities tab and add the command, or check the local policy file.

A job never runs

• The device is offline.
• The schedule is wrong.
• The budget was already hit.
• The task needs a capability the agent does not have.

Read the logs

$ journalctl -u remoteagent -n 50

When to check the server

If every device drops at once, the console or network is the cause. Check the status page, then look at one device’s logs.