Runtime Host

Appearance

Uninstall ​

Two flavors: .deb uninstall (managed by dpkg/apt) and wrapper uninstall (manual). Both leave <host-home> intact unless you explicitly remove it. The home is a normal directory; nothing in it holds the OS hostage.

.deb uninstall ​

Remove (keeps home) ​

bash
sudo apt remove hivecast

The prerm script (projects/matrix-3/packages/hivecast/scripts/build-deb-installer.js:168-179) runs:

  1. systemctl stop hivecast-host.service hivecast-nats.service
  2. systemctl disable hivecast-host.service hivecast-nats.service

Then dpkg removes:

  • /opt/hivecast/
  • /usr/bin/hivecast, /usr/bin/matrix
  • /lib/systemd/system/hivecast-{host,nats}.service

What survives:

  • /var/lib/hivecast/ — the entire home, including JetStream data, credentials, runtime records.
  • /etc/systemd/system/hivecast-{host,nats}.service.d/ — drop-in overrides if you had a workstation-user override.
  • /etc/systemd/journald.conf.d/hivecast.conf — the journald cap.

Purge (removes home + cleanup) ​

bash
sudo apt purge hivecast

The postrm script (build-deb-installer.js:180-195) runs on purge:

  1. Removes /etc/systemd/system/hivecast-{nats,host}.service.d/10-workstation-user.conf and the empty drop-in directories.
  2. Removes /etc/systemd/journald.conf.d/hivecast.conf.
  3. systemctl daemon-reload.

apt purge does not automatically remove /var/lib/hivecast. You have to do that yourself if you want a clean wipe:

bash
sudo rm -rf /var/lib/hivecast
sudo systemctl restart systemd-journald  # apply the journald conf change

It also does not remove the hivecast system user/group. To remove those:

bash
sudo deluser hivecast
sudo delgroup hivecast

Wrapper uninstall ​

The wrapper has no built-in uninstaller. The procedure is:

bash
HOST_HOME=/path/to/host-home

# 1. Stop the Host (also stops the NATS sibling).
hivecast stop --home "$HOST_HOME" 2>/dev/null || true

# 2. Remove the home (or move it aside if you might want to restore).
rm -rf "$HOST_HOME"

# 3. Uninstall the wrapper itself.
npm uninstall -g hivecast

There are no system-level resources to clean up beyond the npm-global files; the wrapper does not register systemd units, launchd plists, Windows services, or any global configuration.

Container uninstall ​

bash
docker compose down
docker volume rm <volume-with-host-home>      # if used named volumes
sudo rm -rf ./credentials                     # the bind-mounted creds
docker rmi <hivecast-worker-image>            # if you don't want the image cached

The docker-compose.yml shipped at projects/matrix-worker/ uses bind mounts (no named volumes), so the only persistent state is in projects/matrix-worker/credentials/.

What an uninstall removes from HiveCast cloud ​

If the Host had a Device Link, the uninstall does not automatically revoke it on the cloud side. The cloud will eventually mark the Device stale (no heartbeats), but the link record persists.

To revoke explicitly before uninstalling:

bash
hivecast logout --home "$HOST_HOME" --revoke-cloud-link

This calls <cloudUrl>/_auth/host-link/revoke with the Host Link token, then clears the local link record. After uninstall, the Device disappears from the cloud's Devices page.

If you forget and uninstall first, you can revoke via the cloud's Devices UI directly — the local link record is no longer needed.

Verifying a clean uninstall ​

bash
# .deb
dpkg -l | grep hivecast                      # should be empty
systemctl list-unit-files | grep hivecast    # should be empty
ls /var/lib/hivecast 2>/dev/null              # only if you wanted to remove

# wrapper
which hivecast 2>/dev/null
npm list -g | grep hivecast

See also ​