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_agent, ask_agents, and remote file access.

The four identifiers

Field	Source	Stability	Use
`ID`	Server-issued UUID	Permanent — survives renames	Scripts, CI, unattended automation
`Hostname`	OS-reported (`os.Hostname()`)	Changes if the OS changes	Default human-facing label
`Name`	User-set friendly label	Changes when you edit it	Renaming a machine without losing its identity
Unique prefix	Computed at resolve time	Same as the longer ID it disambiguates	Convenience — `prod` matches `prod-db-1` only if it is the unique prefix

See internal/connect/machines/types.go:14–60 for the full struct and report 01 §5 for the resolver origin story.

Resolution priority

The order is:

UUID short-circuit.
Exact hostname match.
Exact friendly name match.
Unique fuzzy prefix (prod-1 resolves prod only if no other machine starts with prod).
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.

The `MachineInfo` struct


type MachineInfo struct {
    ID                   string // server UUID
    Hostname             string // os.Hostname() value
    Name                 string // friendly label
    Online               bool   // cached
    HeartbeatAgeSeconds  int    // preferred over Online
    WorkspaceID          string
    AgentVersion         string
    ActiveSession        string
}

HeartbeatAgeSeconds is the source of truth for liveness — Online is a cached boolean that 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. See report 05 §2.6.

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

All consumers — connect exec, ask_agent, ask_agents, and the remotefs.Open file bridge — funnel through the same machines.Resolve(). Behaviour is identical across surfaces.

TAGS: machine-identity, hostname, uuid, resolver, whoami DEPENDS_ON: [daemon, workspaces]