Health

For the platform-side health model, see HiveCast Platform / Devices / Device health. This page is the user/Device perspective: what to expect, what to do when health degrades.

What "online" means

A Device is online if its most recent heartbeat to https://hivecast.ai/_auth/host-link/heartbeat was successful within the heartbeat TTL (about 5 minutes — the schedule sends heartbeats every ~30 seconds).

The Edge dashboard does not show "online/offline" directly — it shows the link card with route metadata. To check online status, look at https://hivecast.ai/apps/web/#dashboard from another Device or browser.

What sends heartbeats

The host.control runtime on the local Device. It runs whenever the Host Service supervisor is up. Stop the Host (hivecast stop) and heartbeats stop; the Device flips to offline within minutes.

Credential refresh

The Device's NATS user JWT has a 24-hour TTL. host.control automatically refreshes via /_auth/host-link/credentials/refresh daily.

Manual refresh:

bash

mx refresh-credentials --home <host-home>

This calls auth.hostLink.credentials.refresh, gets new JWT/seed, persists locally, revokes prior NATS user public keys at the platform.

Manual refresh is rarely needed. Use it if:

You suspect the local credentials might have leaked.
The auto-refresh failed and credentials are about to expire.
You're scripting a credential rotation.

Heartbeat token

Per HiveCast Platform / Security / Capability tokens, a heartbeat token is an opaque random string the Device uses as a bearer for /_auth/host-link/heartbeat. Stored locally in plaintext (it's per-Device, not a shared secret); HMAC-hashed on the platform.

Rotation: every credential refresh rotates the heartbeat token too.

What happens when heartbeats fail

Causes of heartbeat failure:

Network down — Device can't reach hivecast.ai. Heartbeats resume when network returns.
Heartbeat token invalid — local file corruption, or the link was revoked. Re-pair.
Cloud Host down — uncommon; affects everyone, not just one Device.
NATS user JWT expired and refresh failed — manual refresh or re-pair.

After ~5 minutes of failed heartbeats, the Device shows as offline on hivecast.ai/apps/web/#dashboard. Local Edge keeps working; only the cloud-side perception changes.

What happens after refresh

Per HIVECAST-DEVICE-ENROLLMENT-SPEC.md (richard-refresh-proof-20260501-065817):

Old credentials are rejected by the NATS hub immediately.
New credentials connect.
Persistent files (hivecast-link.json and creds files) updated atomically.
Forbidden fields (accountSeed, deviceName, device-meaning displayName) are absent — refreshed records are clean.

Visualizing health

Today's surfaces:

Where	What you see
Edge link card	route key, namespace, Space, authority root if linked
Edge endpoint diagnostics	per-probe state, status code, duration
HiveCast dashboard	online/offline pill per Device, last-seen, runtime counts
`system.devices.devices.list`	full row with `status`, `lastSeenAt`, `revokedAt`

Edge does not surface "is heartbeat working right now." That signal is on the platform-side dashboard.

Restoring a degraded Device

If the platform shows your Device offline and you want to fix it:

bash

# 1. Confirm local Host is up
hivecast status --home <host-home>

# 2. Confirm host.control is running
matrix invoke host.control status '{}' --home <host-home>

# 3. Tail host.control log for heartbeat errors
tail -50 <host-home>/logs/runtimes/host-control.log

# 4. Force a credential refresh
mx refresh-credentials --home <host-home>

# 5. If still failing, check link record exists
matrix invoke system.auth auth.hostLink.list \
  '{"principalId":"<your-id>"}' --home <host-home>

If credentials are missing or invalid, re-pair.

Why no auto-refresh in Edge UI

Edge today does not show heartbeat status, run a refresh button, or display credential expiry. These are target-state features.

The reasoning: Edge is the local control surface. Heartbeat health is a platform concept (the platform decides what counts as alive). The Edge UI for it would be redundant with the platform shell. That said, a Device-side "force refresh" button would be a quick win — the API exists.

Health ​

What "online" means ​

What sends heartbeats ​

Credential refresh ​

Heartbeat token ​

What happens when heartbeats fail ​

What happens after refresh ​

Visualizing health ​

Restoring a degraded Device ​

Why no auto-refresh in Edge UI ​

See also ​