Pairing + status

Nodes use device pairing. A node presents a signed device identity during connect; the Gateway creates a device pairing request for role: node. Device approval admits the connection; the declared command surface needs a separate approval. The direct Apple Watch setup uses an admin-minted, short-lived node-only setup code to approve its fixed low-risk command surface; later capability expansion still requires normal approval.

For manual approval, run these commands on the Gateway:

apus devices list
apus devices approve <deviceRequestId>

Headless node hosts keep reconnecting while device approval is pending, with exponential backoff capped at 30 seconds. After approval, the next reconnect creates a separate command-surface request. Back on the Gateway:

apus nodes pending
apus nodes approve <nodeRequestId>
apus nodes status
apus nodes describe --node <idOrNameOrIp>

If an older client already reports that reconnect is paused, restart the installed node with apus node restart, or stop and rerun its foreground apus node run command once. For an app node paused for manual pairing, restart node mode or the app.

The two request IDs are distinct. Use apus devices reject <deviceRequestId> to reject device admission instead of approving it. An initial unapproved surface has no effective commands. During an expansion, previously approved commands remain effective only while the node still declares them and Gateway policy allows them.

SSH-verified and administrator-minted bootstrap enrollment can approve the first surface automatically. Trusted-network device approval alone does not; inspect nodes pending and approve the surface separately. Later command, capability, or permission expansion still needs approval. Surface approval does not bypass Gateway command policy or local exec approvals.

Pending device-pairing requests expire 5 minutes after the device's last retry — a device that keeps reconnecting keeps its one pending request (and requestId) alive instead of minting a new prompt every few minutes; see Node pairing for the full request/approve lifecycle. If a node retries with changed auth details (role/scopes/public key), the prior pending request is superseded and a new requestId is created — clients get a device.pair.resolved event for the superseded request, and you should re-run apus devices list before approving.

Pending command-surface requests do not expire merely with time; they follow the capability approval lifecycle.

• nodes status marks a node as paired when its device pairing role includes node.
• A connected native Mac reports coalesced activity from interaction with Apus without extra permissions. Optional Settings -> Permissions -> System-wide presence detection also includes physical input in other apps and requires Accessibility. The Gateway marks the freshest eligible Mac as active, gives the agent a stable node-id hint, and routes node connection alerts there before a delayed fallback. See Active computer presence for setup, privacy, timing, and troubleshooting.
• The device pairing record is the durable approved-role contract. Token rotation stays inside that contract; it cannot upgrade a paired node into a role that pairing approval never granted.
• node.pair.* (CLI: apus nodes pending/approve/reject/remove/rename) manages the node's approved command/capability surface on its canonical paired-device record. Device pairing owns both transport authentication and the durable node surface; there is no separate node pairing store.
• apus nodes remove --node <id|name|ip> revokes the device's node role in the paired-device store and disconnects that device's node-role sessions: a mixed-role device keeps its row and only loses the node role, while a node-only device row is deleted. operator.pairing may remove non-operator node rows on other devices; a device-token caller revoking its own node role on a mixed-role device additionally needs operator.admin.
• Approval scope follows the pending request's declared commands:
  • commandless request: operator.pairing
  • non-exec node commands: operator.pairing + operator.write
  • system.run / system.run.prepare / system.which: operator.pairing + operator.admin

Headless node hosts report the hardware model on macOS and Linux.

Connected CLI node hosts and the macOS app report CPU count, load averages, memory, and home-volume disk capacity every 60 seconds, starting on connection. The Gateway exposes the latest snapshot as hostStats in node.list and node.describe. When received, it saves the snapshot on the paired node record, so offline nodes keep showing last-known stats with the original updatedAtMs. Connected nodes use live session stats. apus nodes status and apus nodes describe show a compact stats summary with a last-known age for offline nodes. Windows omits load averages, and unavailable disk capacity is omitted. See Node host stats for the wire contract.

Version skew and upgrade order

The Gateway WebSocket accepts authenticated node clients across an N-1 protocol window. The current v4 Gateway therefore accepts v3 nodes when the connection declares both role: "node" and client.mode: "node". Operator and UI sessions must still use the current protocol.

For staged fleet upgrades, upgrade the Gateway first, then upgrade each node. An N-1 node remains visible and manageable while it is upgraded; the Gateway logs legacy node protocol accepted with an upgrade recommendation. Pairing, device authentication, command allowlists, and exec approvals still apply. Plugin-owned capabilities and commands stay hidden until the node upgrades to the current protocol. Nodes older than N-1 require an out-of-band upgrade before reconnecting.

The direct watchOS HTTPS transport requires the current protocol version; update the watch app with the Gateway before enabling direct mode.