Runtime Host

Appearance

Upgrade ​

A Runtime Host upgrade is "swap the bytes under /opt/hivecast/, re-seed packages/system, restart the services." The Host's home directory format is additive-only, so older homes work with newer binaries. Backwards compatibility goes one direction: do not run an older binary against a newer home.

Linux .deb upgrade ​

bash
# Update the package index, then upgrade just hivecast.
sudo apt update
sudo apt install --only-upgrade hivecast

# Or, for a specific version (downgrade-safe; see Rollback).
sudo apt install hivecast=<version>

The .deb postinst (build-deb-installer.js:272-401) runs on every install:

  1. Re-creates the hivecast user/group if missing.
  2. Re-creates /var/lib/hivecast/ and subdirectories with 0750 mode.
  3. Overwrites host.json with a default config built from ${HIVECAST_BIND_HOST} and the standard NATS settings. This means any hand-edits to host.json are clobbered on apt upgrade.
  4. Overwrites nats-server.conf similarly.
  5. Calls hivecast seed to re-seed packages/system.
  6. Re-applies the units.d/10-workstation-user.conf override if ${SUDO_USER} is non-default.
  7. chown -R the home to the service user.
  8. Re-installs the journald drop-in.
  9. systemctl daemon-reload, then restart both services.

Caution: apt upgrade hivecast clobbers host.json. Back it up first if you have non-default settings. (See Backup.)

After an upgrade, verify:

bash
sudo systemctl status hivecast-host.service hivecast-nats.service
hivecast --version
hivecast doctor --home /var/lib/hivecast --json | jq .

Wrapper / per-user upgrade ​

There is no global package manager for the wrapper install — the wrapper updates by running hivecast install again with a newer wrapper binary. Two patterns:

Pattern A: re-install in place ​

bash
# Install the new wrapper (npm-style).
npm install -g hivecast --registry https://registry.hivecast.ai/api/packages/hivecast-admin/npm/

# Stop the running Host, re-install on top of the same home.
hivecast stop --home "$HOST_HOME"
hivecast install --home "$HOST_HOME"   # re-seeds packages/system, regenerates host.json defaults
hivecast start --home "$HOST_HOME"

hivecast install over an existing home is idempotent for files the wrapper owns:

  • bin/nats-server[.exe] is overwritten.
  • packages/system/ is overwritten via rsync from the wrapper's bundled dist/node_modules/.
  • host.json is generated only if missing — the wrapper does not overwrite an existing host.json. (Different from the .deb postinst, which does overwrite.)
  • credentials/hivecast-install.json is preserved if present.
  • runtimes/ records are preserved.
  • packages/global/ is preserved.

Pattern B: side-by-side new home ​

If you're nervous about the upgrade, install the new wrapper into a new home, link the same Device, and validate:

bash
hivecast install --home "$HOME/.matrix-new"
hivecast login --device --home "$HOME/.matrix-new" --cloud https://hivecast.ai
hivecast status --home "$HOME/.matrix-new" | jq .

If the new home behaves, decommission the old one (back it up first).

Container / worker upgrade ​

Pull the new image, recreate the container:

bash
docker compose pull
docker compose up -d --force-recreate

The container's MATRIX_HOME is volume-mounted, so the home survives. The new image's hivecast install runs on first start (via the container entrypoint.sh) and re-seeds packages/system.

What an upgrade does NOT change ​

  • installId and hostId — the same Device after upgrade.
  • Runtime records — same runtimeIds, same auto-start behavior.
  • User-installed packages in packages/global.
  • Device Link state.
  • Any state under nats/host-default/jetstream/.

What an upgrade MIGHT change ​

  • The bundled NATS version — re-applied from dist/bin/nats-server.
  • Default runtime targets — if the new wrapper added a target to hivecast.mjs:28-39, the next bootstrap-default-runtimes run will register it.
  • Default host.json shape — .deb clobbers, wrapper preserves.

See also ​