Runtime Host

Appearance

Rollback ​

If an upgrade or config change broke things, rollback is "go back to the prior bytes / prior config / prior <host-home>." The Host's schema is additive-only so older binaries work with newer homes, but the cleanest rollback is symmetric: prior binary + prior home.

Rolling back a .deb upgrade ​

Pin a specific prior version ​

bash
# See available versions.
apt list --installed hivecast
apt list -a hivecast

# Install a specific older version.
sudo apt install hivecast=<old-version>

# Hold the version so apt-upgrade won't move it.
sudo apt-mark hold hivecast

To unpin later: sudo apt-mark unhold hivecast.

Combined with a host.json restore ​

The .deb postinst overwrites host.json on every install. If the previous upgrade clobbered a hand-edited config, restore it after the downgrade:

bash
sudo systemctl stop hivecast-host.service hivecast-nats.service
sudo apt install hivecast=<old-version>
sudo cp /path/to/host.json.backup /var/lib/hivecast/host.json
sudo chown hivecast:hivecast /var/lib/hivecast/host.json
sudo systemctl start hivecast-nats.service hivecast-host.service

Verify:

bash
sudo journalctl -u hivecast-host.service -n 100 --no-pager
hivecast doctor --home /var/lib/hivecast --json | jq .

Rolling back a wrapper install ​

bash
hivecast stop --home "$HOST_HOME"

# Install the older wrapper.
npm install -g hivecast@<old-version> --registry https://registry.hivecast.ai/...

# Re-run install on top of the same home (preserves host.json).
hivecast install --home "$HOST_HOME"
hivecast start --home "$HOST_HOME"

Older wrappers may not understand newer fields the wrapper itself wrote into host.json or runtime.json. The schema is additive-only, so unknown fields are ignored, but wrapper logic that depends on a new field will not work. Always pair "downgrade wrapper" with "download home with matching shape" via Backup / Restore when in doubt.

Rolling back a config change ​

The Host normalizes host.json on every read (HostStateStore.loadOrCreateConfig, projects/matrix-3/packages/host-service/src/host-state-store.ts:31-44) and writes the normalized form back. So the simplest config rollback is "swap the file and restart":

bash
# Stop, swap, restart.
sudo systemctl stop hivecast-host.service
sudo cp /path/to/host.json.backup /var/lib/hivecast/host.json
sudo chown hivecast:hivecast /var/lib/hivecast/host.json
sudo systemctl start hivecast-host.service

If the bad change was applied via host.control config.reload, that RPC stops every runtime and restarts them with the new config. There is no transactional revert; you swap the file and trigger another config.reload:

bash
matrix invoke host.control config.reload '{}'

If hivecast login --device produced a bad link record (wrong cloud URL, wrong route key) and you want yesterday's link back:

bash
hivecast logout --home "$HOST_HOME"  # clears the link
sudo cp /path/to/credentials/hivecast-link.json.backup \
       "$HOST_HOME/credentials/hivecast-link.json"
hivecast stop --home "$HOST_HOME"
hivecast start --home "$HOST_HOME"

The host.control heartbeat will resume against the restored cloud URL on the next interval (default 15s).

Rolling back a runtime record ​

The Host re-reads runtime.json on every operation. If a matrix up created a runtime that misbehaves, just matrix down it; the record stays so startup: "auto" would respawn at next Host start. To prevent that, edit the record (or remove the directory entirely). See Runtime records § "Editing records by hand."

When rollback is not enough ​

JetStream state under <home>/nats/host-default/jetstream/ is owned by NATS, not the Host. If a NATS upgrade introduced a stream-format incompatibility, the rollback may need to restore that directory from backup as well. See the NATS server documentation for stream-format compatibility between versions.

See also ​