Device Management

A Device is a linked compute participant that runs HiveCast: a laptop, workstation, server, VM, container, phone, or appliance. Pairing a Device to a HiveCast account turns a local install into a Device that the account can list, inspect, address, and revoke.

The user-facing product term everywhere is Device. Internal data-model terms (installId, hostId, host.json, configName, routeKey) appear only in these reference docs when explaining how the data is stored — never in product UI copy or CLI prose.

Motivation

Devices exist because a Host without a stable identity cannot be coordinated — heartbeat, runtime inventory, address resolution, revocation, and re-pairing all need a durable thing to point at. A Device is a linked compute participant: a laptop, workstation, server, VM, container, phone, or appliance running HiveCast and paired to a Space. The pairing ceremony, the layered identity model (installId, hostId, hostName, deviceSlug), and the lifecycle commands are what make multi-Device topologies coherent — so a Space can hold many machines, each one keeps its place across reboots and reinstalls, and operators can reason about what is actually online. These docs are for you if you are pairing a new Device, managing the Devices you already have, or debugging a heartbeat or identity problem on a real install.

What this docs domain covers

This documentation owns the pairing ceremony, the durable identity contract, the per-Device inventory model, day-to-day operations, and the wire schemas behind every Device record. The platform-side admin perspective lives in docs-platform; the local Edge dashboard lives in docs-edge; the install/CLI surface lives in docs-hivecast.

Where Device fits in the substrate

Matrix is a typed pub/sub/RPC substrate. A Device is the unit of compute: it hosts one or more Runtimes, each of which mounts one or more Packages onto the bus.

Principal -> [owns] -> Device(s)
Device -> [hosts] -> Runtime(s)
Runtime -> [mounts] -> Actor(s)  (Feed / Service / Component)
Device -> [exposes via Driver] -> Resource(s)

Logical actor address (chat, system.inference.openai)
   != Device management path (system.devices.<deviceSlug>)

system.devices is the product/account-facing linked-Device facade. Per P1.43, system.devices is the authority for Device inventory; the platform shell, Edge, the CLI, and federation peers read it directly over the bus. HTTP /api/devices projections exist for non-bus-aware external clients only.

Identity in three layers

Conflating these is the largest single source of UI copy bugs:

Concept	Field	Generated when	Scope
Install identity	installId	First hivecast install (always present)	Per local install, durable
Link identity	hostId	First hivecast login --device (only after pairing)	Per pairing bond
Device label	hostName	Set at pairing or via hivecast login --device --device-name <name>	Mutable human label
Device projection key	deviceSlug	Allocated once by system-auth from hostName, collision-resolved	Stable, address-safe management key under system.devices.<deviceSlug>

installId survives rsync between machines, idempotent reinstalls, and unlink/relink cycles. hostId only exists after pairing. hostName is the mutable display label. deviceSlug is the stable management projection key — it does NOT change when hostName changes. displayName is principal/user identity only; deviceName is forbidden in Device contracts. See CLAUDE.md "Identity lifecycle" for the canonical table.

Sections

• Overview — Device model, vocabulary, and how Device relates to host, runtime, grant, and Resource.
• Pairing — the device-flow / browser-pair / setup-code ceremony, what it produces, and why hosts never receive raw OAuth tokens.
• Inventory — the system.devices actor, heartbeats, online/offline status, runtime visibility, and ownership scoping.
• Operations — pair, disconnect, revoke, rotate, and troubleshoot a real Device against a real Host.
• Reference — the on-the-wire schemas: IDeviceRecord, IHostLinkRecord, the full system.devices op surface, and error codes.

Five-minute orientation

# Pair this local install to a HiveCast account.
hivecast login --device --cloud https://hivecast.ai

# Confirm what was stored.
hivecast whoami
hivecast link-status

# List every Device in your namespace, on the bus.
matrix invoke system.devices devices.list \
  '{"includeOffline":true}'

# Inspect one Device.
matrix invoke system.devices devices.get \
  '{"deviceId":"<deviceSlug>"}'

# Revoke a Device through the bus authority.
matrix invoke system.auth auth.hostLink.revoke \
  '{"hostLinkId":"<id>"}'

The HTTP endpoints /api/devices/* are read-only projections of the bus authority for non-bus-aware external clients (CI, third-party uptime monitors). Substrate consumers always use matrix invoke system.devices ... and matrix invoke system.auth auth.hostLink.*. See P1.43.

Pairing endpoint defaults

The user-facing pairing endpoint URL is the cloud (https://hivecast.ai) by default. Headless and CI flows pair against https://hivecast.ai/_auth/.... For dev work without production traffic, --cloud http://127.0.0.1:3100 is supported (a sibling Host playing the platform role). See HOST-LINKING-LOGIN-MODEL.

Conventions on this site

Every page records the source files it describes in its sourceCode frontmatter and a lastVerified: ISO date. Where current code differs from a target/desired state, the page distinguishes them explicitly with a > **Status: target state — ...** callout. Code is what IS; target state is marked as such.

Authoritative sources: WORKSTREAMS/product-launch/HIVECAST-DEVICE-ENROLLMENT-SPEC.md is the canonical pairing spec. WORKSTREAMS/docker-npm-parity/HOST-LINKING-LOGIN-MODEL.md is the canonical state-machine spec. CLAUDE.md § "Device Link contract" and § "Identity lifecycle" are the day-to-day terminology rules. This package describes what the live code does today as of lastVerified.