Authentication and PINs
Connecting is not one authentication. Different connect operations answer to different credentials, held by different people, and none of them substitutes for another. Knowing which one an operation wants is usually the whole troubleshooting step.
Joining a relay
cmdop join <join-key>The fleet join key decides whether a machine may join a relay. The agent keeps it as its durable credential and presents it on every connection. This is the entire machine sign-in path — there is no browser login and no device-code flow.
Joining answers “may this machine be here”. It says nothing about whether you may open a terminal on some other machine.
Reaching another machine’s terminal
A remote interactive attach authenticates at the target machine’s own relay door, not yours. Two credentials can apply there:
- That relay’s administrator access, which admits you to the door at all.
- The target machine’s connection PIN, when one is armed — a per-machine gate that applies after relay authentication.
Your own machine’s credential is not honoured at another machine’s door. This is deliberate: joining a fleet is not a licence to open a shell on every member of it.
A machine whose relay is LAN-only or loopback-only has no door you can reach remotely, so it is not remotely attachable regardless of credentials.
Connection PINs are owned by the relay
A connection PIN is armed, rotated, and cleared on the relay that owns the target machine — not on the machine doing the connecting, and not by you locally. The relay never reveals a PIN after it is set; it can only tell you whether one is armed.
An interactive attach prompts you for the target’s PIN when it needs one. A loopback or self attach on your own host does not, because you are already the local operator there.
Saving a connection PIN locally
This machine can remember a target’s connection PIN, so attaching to it does not prompt every time:
cmdop connect pin set <machine>
cmdop connect pin status <machine>
cmdop connect pin list
cmdop connect pin clear <machine>This store never prints saved values — list and status tell you what is
stored, not what it is. It is a local convenience copy, not the authority: a
value that no longer matches what the relay armed simply fails, and the fix is
on the target relay — arm a new PIN with cmdop server machine-pin there, then
save the new value here.
This local store does not hold a relay administrator password. That lives with the relay, and putting it here would not grant access.
Related
- Credentials for Connect — which credential each operation needs.
- Security model — every credential in the product, and what each gates.
- Interactive attach
Common questions
Is the join key enough to open a terminal on another machine?
No. The join key lets a machine join a relay. A remote terminal attach uses the target machine’s relay door, that relay’s administrator access, and the target machine’s connection PIN when one is armed.
Where is a connection PIN managed?
The relay that owns the target machine arms, rotates, and clears its connection PIN. The connecting machine can remember a local convenience password, but that local store is not the authority.
Why does the wrong credential keep failing?
Cmdop credentials are separate by design. A credential is accepted only at the door it was issued for, so a join key, relay admin password, connection PIN, and local saved password cannot substitute for each other.