Device pairing

The pairing ceremony is what links one local install (a Device) to one HiveCast principal account. The user-facing term is Device Link; the internal API/storage name is Host Link.

Per WORKSTREAMS/product-launch/HIVECAST-DEVICE-ENROLLMENT-SPEC.md:

There is one attach model, not separate ad hoc flows. The uniform model is:

1. start device enrollment
2. authenticate and approve the enrollment
3. redeem the enrollment on the target runtime
4. issue a device-scoped credential
5. connect and register the runtime

Different surfaces can start the same protocol — local Matrix UI, HiveCast web UI, headless CLI — but they all terminate in the same backend contract and the same device credential model.

Three flows, one ceremony

Flow B: Connect from local Matrix (browser-pair)

(See HIVECAST-DEVICE-ENROLLMENT-SPEC.md Flow B.)

1. Open http://127.0.0.1:3100/apps/edge/ on the local Device.
2. Click Connect to HiveCast.
3. The browser opens HiveCast's login at https://hivecast.ai/....
4. User authenticates (Google / GitHub / etc).
5. HiveCast creates an enrollment, user approves it.
6. The local Edge UI redeems the enrollment via system-auth.
7. The local Device stores the device credential and registers.

Flow C: Connect from HiveCast (browser-side)

(Spec Flow C.)

1. Sign into https://hivecast.ai/.
2. Land on the Devices page.
3. Click Connect another device.
4. HiveCast displays a one-time setup code or device-code URL.
5. On the target Device, run hivecast login --setup-code <code> --cloud https://hivecast.ai.
6. The Device redeems the code and stores the credential.

Flow D: Headless CLI

(Spec Flow D.)

1. Run hivecast login --device --cloud https://hivecast.ai (or hivecast connect https://hivecast.ai).
2. The CLI prints either:
   • a device code + approval URL (the user opens it on a phone or another machine, approves)
   • or waits on a one-time attach token

The CLI loops, polling for approval. Once approved, the Device stores the credential and registers.

All three terminate at system-auth's pairing endpoints. There is no separate code path per surface.

What gets written

After successful pairing, three files in <MATRIX_HOME>/credentials/:

File	Created by	Carries
hivecast-install.json	hivecast install (pre-pairing)	installId — durable per-install id
hivecast-link.json	system-auth.linkGrant redemption	hostId, hostName, deviceSlug, authorityRoot, principal/Space metadata, per-device NATS JWT credentials
host.json	hivecast install (pre-pairing)	local Host config — independent of the cloud link

The link-record schema is owned by mx-cli/src/utils/hivecast-link-store.ts. Reading it directly:

cat /tmp/matrix-home/credentials/hivecast-link.json | jq .

Expected fields (subject to schema evolution):

{
  "kind": "HivecastLink",
  "hostId": "...",
  "installId": "...",
  "hostName": "richard-laptop",
  "deviceSlug": "richard-laptop",
  "authorityRoot": "COM.NIMBLETEC.RICHARD-SANTOMAURO",
  "addressRoot": "COM.NIMBLETEC.RICHARD-SANTOMAURO",
  "spaceId": "spc_7f3a9b2c",
  "spacePath": "alt.stories.ghost-stories.funny",
  "routeKey": "alt.stories.ghost-stories.funny",
  "principal": { "principalId": "...", "displayName": "Richard Santomauro", "email": "..." },
  "cloud": { "url": "https://hivecast.ai" },
  "credentialsRef": "file:credentials/factotum/hivecast-device-creds.creds",
  "linkedAt": "2026-05-04T16:32:11Z"
}

The credentialsRef points at the per-device NATS credentials file — see Security model.

Heartbeat

Once paired, host-control heartbeats periodically to <cloud>/_auth/host-link/heartbeat. The heartbeat carries:

• hostId
• runtime inventory (each runtime's runtimeId, mounts, status)
• Device metadata (CPU, memory, OS, installed packages — at the level the spec allows)

The cloud-side system-auth validates the heartbeat token via auth.hostLink.verifyHeartbeat, then updates system.devices (the platform's Devices facade) and devices.runtimes.register.

A Device whose heartbeat goes stale (default ~3 minutes) is shown as offline in the cloud Devices list. It is NOT auto-revoked — explicit revocation is required.

Inspecting the link

hivecast whoami --home /tmp/matrix-home
# Prints principal/Space/Device summary, exits 0 if linked, non-zero if not

hivecast link-status --home /tmp/matrix-home
# Cloud reachability, last successful heartbeat, last error if any

Re-pairing

Pairing is idempotent at the per-Device level. If hivecast-link.json already exists and you run hivecast login again, the Device re-redeems with the existing hostId. The cloud's system-auth updates lastLinkedAt, possibly issues fresh credentials.

If you want to pair a Device to a different principal, log out first:

hivecast logout --revoke-cloud-link --home /tmp/matrix-home
hivecast login --device --cloud https://other-hivecast.example.com --home /tmp/matrix-home

Revocation

There are three layers, in increasing strength:

Action	Effect
Cloud Devices page → Disconnect device	Cloud-side revocation. Device's heartbeat starts failing on next attempt
hivecast logout --revoke-cloud-link (from the Device)	Same, initiated from the Device
hivecast logout --all (from the Device)	Above + clears hivecast-install.json, regenerating installId on next install

Per HIVECAST-DEVICE-ENROLLMENT-SPEC.md (current implementation status, 2026-04-30):

Host Link revoke is authenticated and principal-bound. Matrix Web has a first-pass Disconnect device action for active linked Devices.

A revoked Device cannot re-pair with the same hostId. It must clear hivecast-link.json locally and start fresh.

Pairing to a non-hivecast.ai endpoint

Any HiveCast-shaped endpoint works:

# Pair to your self-hosted HiveCast
hivecast login --device --cloud https://my-hivecast.example.com --route-key richard

# Pair to a sibling local Host (the dev two-runtime topology)
hivecast login --device --cloud http://127.0.0.1:3100 --route-key dev-pair-test

The --cloud URL must serve the HiveCast pairing endpoints (OAuth + /_auth/host-link/...). A Host with auth.mode: 'public-session' and OAuth provider credentials configured does this.

What pairing does NOT do

• It does NOT move execution off the Device. Inference still runs on the Device.
• It does NOT move credentials off the Device. Inference credentials stay in Factotum.
• It does NOT change the local Host's auth.mode. A paired Device with auth.mode: 'local-client' still treats loopback as local owner — pairing only adds account-aware routing on top.

See also

• Login — sense 1 (browser sign-in to the cloud).
• Spaces — the public-Space-path concept that pairing references.
• Security model — per-device credentials.
• CLI → hivecast login / whoami / logout — wrapper-side reference.
• Quickstart → Login / pair a device — hands-on.
• Troubleshooting → Device pairing failed.

Source: WORKSTREAMS/product-launch/HIVECAST-DEVICE-ENROLLMENT-SPEC.md; projects/matrix-3/packages/system-auth/src/host-auth.ts (generateHostId, link-grant logic); projects/matrix-3/packages/mx-cli/src/utils/hivecast-link-store.ts (link-record IO); projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 1595-1635 (runHiveCastLinkCommand).