HiveCast Product

Appearance

Uninstall ​

There is no hivecast uninstall command. Removal is by package manager (.deb) or by removing the source checkout. This page covers both, plus what state survives by default and when to clear it.

On a .deb install ​

Stop services first ​

bash
sudo systemctl stop hivecast-host.service hivecast-nats.service

Not strictly necessary — prerm does this — but explicit is safer.

Soft remove (apt remove) ​

bash
sudo apt remove hivecast

What prerm runs (scripts/build-deb-installer.js:168-179):

bash
systemctl stop hivecast-host.service
systemctl stop hivecast-nats.service
systemctl disable hivecast-host.service
systemctl disable hivecast-nats.service

Then dpkg removes:

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

What stays:

  • /var/lib/hivecast/ — including host.json, all credentials, all runtime records, all logs, the JetStream data dir
  • /etc/systemd/system/hivecast-{nats,host}.service.d/10-workstation-user.conf — the workstation-user drop-in
  • /etc/systemd/journald.conf.d/hivecast.conf — the journald cap

This is intentional: a soft remove preserves credentials and state in case you reinstall.

Hard remove (apt purge) ​

bash
sudo apt purge hivecast

postrm runs additionally (scripts/build-deb-installer.js:180-195):

bash
rm -f /etc/systemd/system/hivecast-nats.service.d/10-workstation-user.conf
rm -f /etc/systemd/system/hivecast-host.service.d/10-workstation-user.conf
rmdir /etc/systemd/system/hivecast-nats.service.d 2>/dev/null || true
rmdir /etc/systemd/system/hivecast-host.service.d 2>/dev/null || true
rm -f /etc/systemd/journald.conf.d/hivecast.conf
systemctl daemon-reload

What still stays even after purge:

  • /var/lib/hivecast/
  • the hivecast system user/group

dpkg's purge semantics doesn't auto-delete a state directory; you have to remove it manually:

bash
sudo rm -rf /var/lib/hivecast/
sudo deluser hivecast
sudo delgroup hivecast

Caution: /var/lib/hivecast/credentials/hivecast-link.json carries a per-Device NATS JWT. Removing it locally does NOT revoke the cloud-side link record. Always run hivecast logout --revoke-cloud-link (or revoke from the HiveCast Devices page) before wiping /var/lib/hivecast. Otherwise the cloud will still consider this Device linked until heartbeat goes stale.

On a source-checkout install ​

There's nothing to "remove" at the system level — the binaries live in the workspace.

bash
# Stop the Host first
hivecast stop --home /tmp/matrix-home

# Confirm everything is down
ls /tmp/matrix-home/host.status.json /tmp/matrix-home/host.pid 2>/dev/null   # should be gone
ls /tmp/matrix-home/nats/host-default/nats-server.pid 2>/dev/null            # should be gone

# Remove the symlink if you made one
sudo rm -f /usr/local/bin/hivecast

# Remove the Host home
rm -rf /tmp/matrix-home

If you used ~/.matrix (the default), substitute. The git clean -fdx of the workspace itself takes out the build artifacts — that's separate from removing a Host install.

If you want to keep the local Host but disconnect from the HiveCast account:

bash
hivecast logout --revoke-cloud-link --home /tmp/matrix-home

Effects (per hivecast.mjs:1770-1774):

  • Calls the cloud's revocation endpoint, marking this Device unlinked there.
  • Deletes <host-home>/credentials/hivecast-link.json locally.
  • Leaves <host-home>/credentials/hivecast-install.json intact (the installId is preserved).
  • The Host keeps running. Next start it'll come up as local-only.

Use --all to also wipe hivecast-install.json — the next install will regenerate the installId. Almost always not what you want.

Removing one runtime without uninstalling ​

bash
# Stop the runtime
hivecast down <runtime-id> --home /tmp/matrix-home

# Remove its directory if you don't want it auto-restarted
rm -rf /tmp/matrix-home/runtimes/<runtime-id>/

# Optional: remove its log files
rm -f /tmp/matrix-home/logs/runtimes/<runtime-id>.{stdout,stderr}.log

Just deleting the runtime directory while the Host is running won't stop the process — hivecast down is required first.

Removing one package without uninstalling ​

bash
hivecast down <package-or-mount> --home /tmp/matrix-home   # stop everything using it
rm -rf /tmp/matrix-home/packages/global/node_modules/<package>/

Note that re-running hivecast install will re-mirror the bundled package set — if <package> is in the bundled set, it'll come back. Edit dist/node_modules/ upstream or use matrix install from a different registry to override.

What happens if I just rm -rf /tmp/matrix-home while the Host is running? ​

The Host will keep running with the in-memory state it has, but every subsequent operation that needs a file (logs, runtime registration, status update) will error out. Eventually it'll crash. The NATS sibling will be similarly broken — its data dir is gone.

Always stop the Host first. Then remove the home.

Reinstalling ​

After removing, a fresh hivecast install (or dpkg -i) treats the machine as clean. If you kept <MATRIX_HOME> (apt remove without purge):

  • host.json is preserved
  • hivecast-install.json is preserved (your installId survives)
  • bundled packages are re-mirrored fresh
  • runtime records may be inconsistent with the new bundle — hivecast seed will report any corruption

If you removed <MATRIX_HOME> (rm -rf or apt purge followed by manual rm): a fresh install regenerates everything, including a new installId. Cloud pairing has to happen again.

See also ​

Source: projects/matrix-3/packages/hivecast/scripts/build-deb-installer.js lines 168-195 (prerm/postrm) and 296-302 (/var/lib/hivecast ownership).