Machines & Identity

Every Connect operation — interactive attach, one-shot exec, agent-to-agent calls, remote filesystem reads — funnels through a single resolver that turns the string you type into a concrete machine in the active fleet. This page describes what that resolver knows about a machine and how it picks one.

The four identifiers

A machine carries four kinds of names. They are not interchangeable:

The machine record every Connect tool sees carries:

Resolution priority

The resolver tries the input string against the machine list in this order, stopping at the first match:

1. UUID short-circuit. If the input matches the canonical 8-4-4-4-12 UUID shape (case-insensitive), it is matched against the machine’s ID. No fall-through — if no UUID matches, you get an error, not a fuzzy guess.
2. Exact hostname. Equal to Hostname after lowercasing.
3. Exact display name. Equal to Name after lowercasing. Useful when the friendly label diverges from the OS hostname.
4. Unique fuzzy prefix. A substring or prefix match across both Hostname and Name. If exactly one machine matches, it wins.
5. Ambiguous. Two or more candidates → error with a candidate list.
6. No match. Error with the input echoed.

Online flag vs heartbeat age

The Online flag is a cached boolean populated by the relay. It reflects what the dashboard saw at the last list refresh, which can lag real state by seconds to minutes. For freshness-sensitive logic the authoritative signal is HeartbeatAgeSeconds:

• 0–30s — recent heartbeat, machine is live.
• 30–90s — possibly degraded; the daemon may be running but its relay link is flaky.
• >90s — server will mark the machine offline on the next sweep.

The agent tool surface uses Online as the gate (online_only=true is the default for ask_machines, false for connect list), but when you need to debug a flaky machine, HeartbeatAgeSeconds is the number to look at.

The whoami operation

The connect agent tool exposes operation=whoami, which is the simplest way to ask “where am I?” from inside an agent prompt:

{
  "operation": "whoami"
}

It reads the host’s own hostname and matches it against the fleet’s machine list (case-insensitive). The result is one of:

{ "matched": true, "hostname": "mac-studio", "machine_id": "8f23..." }
{ "matched": false, "hostname": "mac-studio", "reason": "not in workspace" }
{ "matched": false, "hostname": "mac-studio", "reason": "api unreachable" }

If the API is unreachable, whoami degrades gracefully: it still returns the local hostname so prompts can use it as context.

Listing machines

The CLI surfaces three views of the machine list:

# All machines in the active fleet.
cmdop connect --list
 
# Only the ones currently online.
cmdop connect --list --online
 
# JSON for scripting.
cmdop connect --list --json

A typical row in the human-readable output looks like:

NAME              HOSTNAME           ID         ONLINE  AGE     SESSION
mac-studio        mac-studio.local   8f23...    yes     4s      —
prod-api-1        prod-api-1         a142...    yes     12s     active (jane@bmw)
vps-audi          vps-audi           c9f8...    no      4m12s   —
vps-bmw           vps-bmw            f200...    yes     3s      —

The SESSION column is populated from the machine’s active-session info. It shows whether somebody else is currently attached.

Fuzzy matching pitfalls

Two patterns cause confusion:

1. Ambiguous prefixes. If you type prod and the fleet contains prod-api-1, prod-api-2, prod-db-1, the resolver returns:

   ambiguous machine "prod" — matches: prod-api-1, prod-api-2, prod-db-1

   The fix is to type more characters until exactly one machine matches, or to use the UUID prefix instead.

2. macOS .local suffix. On macOS, the OS-reported hostname is often mac-studio.local. The resolver matches this permissively — both mac-studio and mac-studio.local resolve to the same machine.

A single-character prefix is rejected outright to avoid surprises. Use at least two characters when matching by prefix.

Renaming a machine

The OS hostname and the friendly name can both change. The machine’s UUID cannot. Rename flow:

• Edit the friendly name from the desktop app’s machines tab or the dashboard.
• Or change the OS hostname; the agent re-registers under the new value on its next heartbeat.

For the duration of the legacy reconciliation window (server-side), the old hostname continues to resolve. Long-running scripts should switch to UUID before assuming the rename has propagated everywhere.

Active session info

When somebody is attached to a machine, the active-session info carries enough for the dashboard and TUI picker to show “already in use” hints — the session ID, when it started, and the operator (the hostname of the client that opened the session).

This is purely informational — multiple clients can attach to the same session. The desktop app uses it to dim machines that already have an operator. See interactive-attach for the multi-client model.

Cross-fleet addressing

A machine belongs to exactly one fleet. To talk to a machine in a different fleet, select it with the --workspace flag (it keeps its legacy name):

cmdop connect --workspace staging exec vps-bmw -- uptime

There is no syntax for “machine X in fleet Y” in a single call without the flag — that is by design, because the relay enforces fleet scoping at the auth layer.

Related