Runtime Host

Appearance

Restore ​

Restoring is the inverse of Backup. The home directory is portable: drop a backup back into place, run hivecast seed to rehydrate the bundled package store, then hivecast start.

When to restore ​

  • After a failed upgrade.
  • After hardware migration to a new machine.
  • After a corrupted disk.
  • After a Device Link mistake (you want yesterday's link record back).

Procedure (.deb / systemd install) ​

bash
# 1. Stop services so nothing writes to /var/lib/hivecast.
sudo systemctl stop hivecast-host.service hivecast-nats.service

# 2. Move the broken home aside (do not delete until restore is verified).
sudo mv /var/lib/hivecast /var/lib/hivecast.broken-$(date +%s)

# 3. Restore the backup tarball.
sudo mkdir -p /var/lib/hivecast
sudo tar -xzf hivecast-backup-YYYYMMDD.tar.gz -C / \
    --strip-components=2  # adjust based on tarball layout

# 4. Fix ownership.
sudo chown -R hivecast:hivecast /var/lib/hivecast

# 5. Remove volatile files that should not be in a backup but might be.
sudo rm -f \
  /var/lib/hivecast/host.status.json \
  /var/lib/hivecast/host.pid \
  /var/lib/hivecast/host.start.lock
sudo rm -rf /var/lib/hivecast/runtime-env

# 6. Re-seed the bundled package store. Idempotent.
sudo -u hivecast hivecast seed --home /var/lib/hivecast | jq .

# 7. Re-drop the bundled NATS binary if missing.
[ -x /var/lib/hivecast/bin/nats-server ] || \
  sudo cp /opt/hivecast/dist/bin/nats-server /var/lib/hivecast/bin/

# 8. Start NATS first, then the Host (Requires= dependency enforces this).
sudo systemctl start hivecast-nats.service
sudo systemctl start hivecast-host.service

# 9. Verify.
sudo systemctl status hivecast-host.service hivecast-nats.service
sudo -u hivecast hivecast status --home /var/lib/hivecast | jq '.status'
sudo -u hivecast hivecast runtimes --home /var/lib/hivecast | jq '.runtimes | length'

If hivecast seed reports runtimeRecords.corrupt non-empty, deal with it now (typically: delete the named directories and re-create the runtimes via matrix up). The Host will not silently respawn from a corrupt record, but it will attempt to bootstrap healthy ones around it (parse-and-skip, projects/matrix-3/packages/host-service/src/host-state-store.ts:106-142).

Procedure (wrapper / per-user install) ​

bash
HOST_HOME=/path/to/host-home
hivecast stop --home "$HOST_HOME" 2>/dev/null || true

mv "$HOST_HOME" "${HOST_HOME}.broken-$(date +%s)"
mkdir -p "$HOST_HOME"
tar -xzf hivecast-backup-YYYYMMDD.tar.gz -C "$(dirname "$HOST_HOME")"

rm -f \
  "$HOST_HOME/host.status.json" \
  "$HOST_HOME/host.pid" \
  "$HOST_HOME/host.start.lock"
rm -rf "$HOST_HOME/runtime-env"

hivecast seed --home "$HOST_HOME" | jq .
hivecast start --home "$HOST_HOME"
hivecast status --home "$HOST_HOME" | jq .
hivecast runtimes --home "$HOST_HOME" | jq '.runtimes | length'

Cross-machine restore ​

The home directory is not machine-keyed. You can restore a backup made on machine A onto machine B and the Host will start. The installId and hostId carry over, which is the right behavior: the same Device should remain the same Device after a hardware swap.

What does NOT carry over:

  • The exact NATS pid (recomputed).
  • The exact HTTP port (re-allocated unless pinned in host.json).
  • The exact hostNatsStatus URL (rebuilt from host.json).

If you want to fork a Host (one becomes two), regenerate credentials/hivecast-install.json on the new home before its first start. Otherwise both Hosts will heartbeat the same installId to HiveCast, which is wrong.

Verifying after restore ​

bash
# Did the Host start cleanly?
sudo journalctl -u hivecast-host.service -n 100

# Are runtimes healthy?
sudo -u hivecast matrix invoke host.control runtime.list '{}' \
  | jq '.runtimes[] | { id: .runtimeId, status, ch: .metadata.controlHealthStatus }'

# Did the Device Link survive?
sudo -u hivecast hivecast link-status --home /var/lib/hivecast | jq .

If the Device Link reports linkStatus: "stale", the cloud has not seen a heartbeat from this Host recently. Wait one heartbeat interval (15s) and recheck; if still stale, see Diagnostics.

See also ​