Device pairing status

The HiveCast link card on the Edge dashboard tells you whether this Device is paired to a HiveCast account, and if so, what route metadata applies.

What the card shows

Source: main.ts:644-669 (renderLinkCard).

Field	Meaning
route key	Public Space path, e.g., alt.stories.ghost-stories.funny. not linked if not paired. May show <value> (detected) if Edge inferred from hostname.
namespace	Typed form, e.g., space.alt.stories.ghost-stories.funny. not present if not paired.
Space	Durable spaceId. not present if not paired.
authority root	Bus root, e.g., SPACE.SPC_XXX. not present if not paired.

Status pill: green linked if paired, neutral optional if not.

How the data flows

Edge's bootstrap probe (/api/bootstrap) returns these fields when present. Source: edge-model.ts BootstrapPayload:

interface BootstrapPayload {
  routeKey?: string;
  publicNamespace?: string;
  canonicalNamespace?: string;
  spaceId?: string;
  authorityRoot?: string;
  authenticated?: boolean;
  principal?: { ... };
  ...
}

When the Device is paired to HiveCast, host.control exchanges credentials and the local gateway includes the link metadata in its bootstrap response.

What "linked" means

Source: edge-model.ts:212-219 (isLinked).

isLinked(bootstrap) =>
  bootstrap.state === 'ok' && (
    bootstrap.data?.routeKey
    || bootstrap.data?.publicNamespace
    || bootstrap.data?.spaceId
  )

The presence of any one of routeKey, publicNamespace, or spaceId implies linked. In practice all three appear together post-pair.

Detected route key

Source: edge-model.ts:255-267 (detectPreviewRouteKey).

If bootstrap.routeKey is missing but the hostname ends with .hivecast.ai, Edge infers the first hostname label as a candidate route key. Excluded labels: hivecast, www, registry. Detected route keys are displayed with a (detected) source tag — they are not used for actions, only for display.

This handles the case where someone visits a preview URL like https://my-preview.hivecast.ai/... without a real session.

What you can do from the card

Just below the card is the action panel (main.ts:357-387):

• Connect to HiveCast if not linked. Opens /auth/link?routeKey=<routeKey> if a route key is detected, else /auth/link.
• Manage devices if linked. Opens https://hivecast.ai/apps/web/#devices.

Plus a "Open route-key Director" link if a route key is present, that opens the linked-Space Director URL.

What pairing changes

After pairing:

• Local owner mode keeps working on 127.0.0.1. You stay in control on your laptop.
• Public route added. https://hivecast.ai/<routeKey>/edge/ now serves Edge for this Device. https://hivecast.ai/<routeKey>/director/ works similarly.
• Per-Device NATS user JWT issued. Stored in <host-home>/credentials/.
• Heartbeat token issued. Used for /_auth/host-link/heartbeat.

Pairing does NOT mean

• Your inference credentials moved to HiveCast (they did not — they stay local per Rule 4).
• Your apps run on HiveCast (they did not — they run on your Device).
• The platform owns your local install state (it does not — local state stays local).

Per CONSTRAINTS.md C11 ("Durable local ownership remains local"), pairing is additive. The cloud routes; the Device executes.

Refreshing pair state

Edge does not show pair-flow progress live. After pairing succeeds, refresh Edge to pick up the new bootstrap.

Detecting credential expiry

The Device's NATS user JWT has a 24-hour TTL. The Host's host.control automatically refreshes it via auth.hostLink.credentials.refresh. Edge does not show TTL or refresh status today (target state).

If the JWT expired and refresh failed, the Device cannot reach the cloud bus. Cloud-routed URLs may fail; local URLs still work.

When the card shows "not linked" but you think you paired

Possible causes:

• The pair flow never completed exchange. Check <host-home>/credentials/hivecast-link.json exists.
• The Host needs restart to pick up the new credentials. hivecast stop && hivecast start.
• The bootstrap is being served by a stale process. Force-reload the page.

If still "not linked" after these:

matrix invoke system.auth auth.hostLink.list \
  '{"principalId":"<your-principal-id>"}' --home <host-home>
# If the link exists, it should appear here.

See also

• Device Management / Pair — pairing flow.
• Device Management / Disconnect — unpairing.
• Device Management / Health — heartbeat status.
• HiveCast Platform / Overview / Devices — platform-side concepts.

Source: projects/matrix-3/packages/matrix-edge/src/main.ts:644-669 for the card. edge-model.ts:212-276 for the linked / detect logic.