Relay operation issues
A relay you run yourself is just the cmdop binary: if the process is up and its
address answers, the relay works. Run cmdop server status and cmdop logs -f
first. Most problems are one of four — it was never created, it is in the wrong
reachability mode, the admin password was lost, or the join key was cleared.
The relay is the cmdop binary. There is no separate service, database, or
cache to check — if the process is up and its address answers, the relay is
working.
cmdop server status
cmdop logs -fIf it is not running, start it detached:
cmdop server --detachCommon problems
| Symptom | What to do |
|---|---|
| The relay will not start | Read cmdop logs -f. A relay that was never created has no configuration — run cmdop server create first. |
cmdop server create refuses to run | It will not overwrite an existing configuration. Pass --force only if you mean to replace it. |
| You lost the browser admin password | cmdop server admin-password --reset on the relay host. |
| Machines connect, but nobody can reach the console | Check the mode you created it in. A LAN relay is only reachable on its private network — see Connection issues. |
| Machines stopped connecting after a change | Machine connections can be paused from Server → Connections in the web console; the console stays up while they are. Check the Server health dot. |
| New machines cannot join | The join key may have been cleared. Read or rotate it at Server → Security, or with cmdop server join-key. |
| Authentication fails after switching relays | Credentials are per relay. Join against that relay — see Joining and access issues. |
| Uploads report storage full | The relay’s attachment budget is exhausted and nothing further can be reclaimed safely. Raise attachments.quota_bytes in server.yaml and restart. |
Rotating without breaking things
Rotating the fleet join key keeps already-joined machines connected — it only affects new joins. Clearing it blocks new joins entirely. Resetting the relay admin password does not touch the join key, connection PINs, or your inference credential; those are separate credentials.
Check what the relay thinks it is
Server → Overview in the web console reports whether the relay is running, the address it advertises to machines, how many machines are connected, its uptime, its mode, and its version. When a machine cannot find the relay, compare the advertised address with the address the machine joined against — a mismatch there is the usual cause.
Related
Common questions
Why will my self-hosted relay not start?
Run cmdop server status and cmdop logs -f on the relay host. If the relay was
never created, run cmdop server create before starting it detached.
Why can machines connect but I cannot reach the console?
Check the relay mode and advertised address. A LAN relay is reachable only on its private network; a public or own-domain relay needs the matching reachable door.
Does rotating the join key disconnect existing machines?
No. Rotating the fleet join key affects new joins. Already joined machines keep their stored credential; clearing the key stops new machines from joining until you create another one.
Cmdop