Machine Identity

A machine in CMDOP has one stable identifier (a server-issued UUID) and several human-friendly ones. Every cross-machine call funnels through one resolver so the rules below apply uniformly to connect exec, ask_machine, ask_machines, and remote file access.

The four identifiers

Resolution priority

The order is:

1. UUID short-circuit.
2. Exact hostname match.
3. Exact friendly name match.
4. Unique fuzzy prefix (prod-1 resolves prod only if no other machine starts with prod).
5. Ambiguous — return the candidate list as an error.

Single-character prefixes are rejected to avoid surprises. Hostnames ending in .local (common on macOS) are matched permissively.

What a machine record carries

Each machine record exposes:

Heartbeat age is the source of truth for liveness — the cached online flag may lag the relay TTL by up to a heartbeat interval.

The whoami operation

cmdop connect exposes a whoami operation that the agent uses when it needs to confirm which machine it is on:

{
  "operation": "whoami"
}

Returns:

{
  "hostname": "laptop-a.local",
  "matched": true,
  "machine_id": "01HX9F7E8Z..."
}

If the relay is unreachable, the call degrades gracefully — matched=false with no machine_id.

Fuzzy match pitfalls

• Ambiguous prefix. Querying prod when both prod-1 and prod-2 exist returns a machine list, not a single match. Use the longer prefix or the UUID.
• Single-character prefix. Rejected. p will never match anything.
• .local suffix. macOS hostnames often end in .local; the resolver strips it for hostname comparison.

Renaming a machine

Hostname and friendly name can change. The server UUID cannot. On the next heartbeat the agent re-registers under the new name; the relay keeps the old hostname as an alias for a short reconciliation window so existing references keep working.

Best practice for scripts

Prefer the UUID in CI and unattended scripts — it is immune to renames and ambiguity. Use hostname or fuzzy prefix in interactive flows where typing a UUID is impractical.

# good — unambiguous
cmdop connect exec --id 01HX9F7E8Z... -- uptime
 
# fine for humans — fuzzy prefix
cmdop connect exec prod-1 -- uptime

Related

• Agent Communication
• Daemon
• Fleets
• Remote Sessions