Runtime Host

Appearance

Host vs device ​

The product calls a linked install a Device. Internally the durable records and supervisor surfaces use the term Host (and the older internal term Host Link for the cloud pairing). They are related but not the same concept; conflating them creates real bugs.

Identity table ​

The repo's CLAUDE.md documents the canonical identity table. The relevant rows for this section:

ConceptFieldFileWhen generated
Install identityinstallId<host-home>/credentials/hivecast-install.jsonFirst hivecast install
Link identityhostId<host-home>/credentials/hivecast-link.jsonFirst hivecast login --device
Device labelhostName<host-home>/credentials/hivecast-link.jsonAt pairing or via --device-name
Device projection keydeviceSlug<host-home>/credentials/hivecast-link.jsonAllocated by system-auth from hostName

The Host (the supervisor, this domain's subject) always exists for a running install. The Device (a linked Host with hostId + deviceSlug) only exists after a successful pairing ceremony with HiveCast or a sibling Host playing the platform role.

Practical implications ​

  • A standalone local Host runs all five default runtimes (system, host-control, gateway, web, edge) without ever linking a Device. Visit http://127.0.0.1:3100/apps/edge/. There is no "Device" yet, just a Host.
  • After hivecast login --device --cloud <url>, system-auth issues a hostId, allocates a deviceSlug, and the Host's host-control runtime begins emitting heartbeats.
  • The heartbeats go in two directions:
    1. To the local system.devices actor via NATS (HostControlActor._registerLocalDeviceHeartbeat, host-control/src/HostControlActor.ts:278-314).
    2. If cloudUrl is set on the link, also to <cloudUrl>/_auth/host-link/heartbeat over HTTPS (HostControlActor.postCloudDeviceHeartbeat, host-control/src/HostControlActor.ts:463-498).

Where Devices live in the bus ​

system.devices is the inventory/control facade for Devices. It is not the public actor namespace. Actors mount under their own subjects (chat, director, etc.). system.devices.<deviceSlug> is a management projection, not a routing namespace. The repo CLAUDE.md § "Device Link contract" is the authoritative statement.

Forbidden conflations ​

  • deviceName is forbidden in the Device contract (use hostName for the human label, deviceSlug for the management key).
  • The user-facing word is Device. Never put installId, hostId, host.json, or configName in product UI copy.
  • hostName change does not change deviceSlug. deviceSlug is stable and address-safe.

When the difference matters ​

If you are operating a server fleet or a worker cell, the question "how many Hosts?" is the supervisor count — equal to the number of running MatrixHostService processes, one per <host-home>. The question "how many Devices?" is the linked-install count, which is the number of distinct hostId values successfully approved by system-auth. A laptop with two Host homes and two Devices is not a contradiction.

See also ​