Connection issues
When cmdop status says Unreachable, the agent is running fine and the relay
address is what did not answer — so check the address before the network. A bare
host means plaintext LAN ports; a public or own-domain relay needs its full
https:// URL. Remote terminal attach is separate: it requires the target to sit
behind a public or own-domain relay.
Start with the verdict and the logs on the machine that is not connecting:
cmdop status
cmdop logs -fIf status says Unreachable, the agent is running and the relay address did
not answer. Work through the address first — it is the usual cause.
The relay’s addresses
A relay in LAN mode listens on HTTP 63141 and gRPC 63142. A bare host in a
Cmdop address resolves to that pair:
| You wrote | HTTP base | gRPC dial | TLS |
|---|---|---|---|
192.168.1.50 | http://192.168.1.50:63141 | 192.168.1.50:63142 | no |
192.168.1.50:9000 | http://192.168.1.50:9000 | 192.168.1.50:63142 | no |
https://relay.example.com | https://relay.example.com | relay.example.com:443 | yes |
Public and own-domain relays terminate TLS at their own door on 443, so a bare
host is the wrong form for them — give the full https:// URL.
Common causes
| Symptom | What to do |
|---|---|
| A bare host resolves to the wrong place | You are probably behind a proxy or a non-default layout. Give an explicit https:// URL instead of a bare host. |
| A plaintext LAN relay refuses the connection | Join with --insecure. Authenticated plaintext is acceptable only on loopback or a private network. |
A public host over http:// is refused | Use https://. Public and own-domain doors do not accept plaintext. |
cmdop remotes add fails its health probe | The relay is not up, or a firewall blocks it. Start it, open the port, or stage the entry with --no-check. |
| Works on the relay host, not from another machine | The LAN listeners are bound to loopback or blocked. Bind and firewall them for the private network, and use the host’s reachable private address. |
| Authentication fails right after switching relays | Credentials are per relay — join against the new one. See Joining and access issues. |
Do not expose the LAN listeners directly to the internet. If you need reach from
outside the network, that is what the public and own_domain relay modes are
for — see Self-hosted relay.
Attaching to a remote machine
cmdop connect <machine> needs the target to be online and behind a relay
with a public or own-domain door. The command asks for that relay’s admin
password and, when armed, the target machine’s connection PIN.
LAN-only machines are not remotely attachable. That is a property of the relay’s reachability mode, not a fault — decide it when you create the relay.
The no-argument picker lists only other online machines. It hides this machine and any coordinator members, because those are chat targets rather than attachable terminals. Naming a host explicitly still resolves exactly, even if that host is offline.
cmdop connect exec is narrower: it runs against this host’s own relay. Use an
attached session for a machine you reach through a public relay edge.
Common questions
Why does cmdop status say Unreachable?
The agent process is running, but the relay address did not answer. Check the
address first: LAN relays use plaintext private-network addresses, while public
or own-domain relays need their full https:// URL.
Why can the console reach a machine but terminal attach cannot?
Console reach and remote terminal attach use different reachability requirements. The console can route to any online joined machine through the relay, but terminal attach also needs the target’s own public or own-domain relay door and its authentication.
Do I need port forwarding for a joined machine?
No. A normal joined machine dials out to its relay. Port binding decisions apply to the relay door you choose to operate, not to every agent machine in the fleet.
Cmdop