Troubleshooting
Troubleshooting Cmdop starts with cmdop status on the affected machine. It
reports the process, the relay it is pointed at, the connection state, and — for
every state that is not Connected — the reason and the next step. Read that
verdict before changing anything; it names which of the four common failures you
actually have.
Almost every Cmdop problem starts with one question: is this machine connected?
cmdop status answers it in one screen and names the reason when the answer is
no.
cmdop statusRead the verdict
status reports the process, the relay it is pointed at, the connection state,
and the reason. Every state that is not Connected names both a cause and a
next step:
| State | What it means | What to do |
|---|---|---|
| Connected | The machine is reachable and working. | Nothing. |
| No process | The agent is not running. | cmdop start |
| Starting / Connecting | The agent came up and is dialing the relay. | Wait — cmdop start blocks until the real connection completes. |
| Reconnecting | The connection dropped and the agent is retrying. | Wait. If it persists, see Connection issues. |
| Stopped by you | The agent was deliberately stopped. | cmdop start |
| Unreachable | The relay address did not answer. | Check the address and the network — see Connection issues. A plaintext LAN relay needs --insecure at join. |
| Auth rejected | The stored credential is stale or was revoked. | Join again: cmdop join <join-key> — see Joining and access issues. |
On Auth rejected, some installed versions still print a hint pointing at
cmdop login. Ignore it — cmdop login is retired. cmdop join is the only
way a machine comes online.
cmdop start derives its verdict from the same classifier, so the two commands
never disagree. If start says it is still connecting, it prints the last
attempt’s reason rather than claiming success.
Look at the logs
cmdop logs -fstatus keeps its log tail off by default so the “am I connected?” check stays
readable. Pass -l (or --logs) to append recent lines to the status screen
instead.
Check the installation itself
cmdop doctordoctor diagnoses the installation and environment rather than a connection.
Reach for it when cmdop behaves oddly on a host, not when a machine is
offline.
Common questions
Why is my Cmdop machine offline?
Run cmdop status on that machine first. If it says No process, start the
agent. If it says Unreachable, check the relay address and network path. If
it says Auth rejected, join again with a current fleet join key.
What should I check before changing relay settings?
Read the status verdict and follow the named next step. Most connection
problems are address, process, or credential problems, not a reason to rebuild
the relay. Use cmdop logs -f only after the verdict points at the failing
layer.
Does troubleshooting require opening ports on the machine?
No. A joined machine normally needs only its outbound connection to the relay. Open or bind relay ports only when you are operating the relay itself or deliberately making a relay door reachable.
Go deeper
Auth rejected, and which credential each surface actually wants.
Connection issuesUnreachable relays, and what remote attach requires.
Performance issuesFind the slow layer before you change anything.
Relay operation issuesWhen your own relay will not come up.
Machine behind NATConfirm when no port forwarding or VPN is required for AI assistant access.
Server without SSHDiagnose the joined-server path before exposing an SSH daemon.
Cmdop