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.

Passwords stored on this machine

Separately from all of the above, this machine can remember the attach password for a password-protected agent, so agent-to-agent work does not prompt every time:

cmdop connect password set <machine>
cmdop connect password status <machine>
cmdop connect password list
cmdop connect password 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 the target simply fails, and the fix is on the target relay.

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.