Runtime Host

Appearance

Linux systemd ​

This is the production install for Linux. The hivecast .deb package installs two systemd units that supervise NATS and the Host as independent services. The unit definitions are emitted by projects/matrix-3/packages/hivecast/scripts/build-deb-installer.js.

Build and install ​

bash
# Build the .deb (must run on Linux with dpkg-deb).
pnpm --filter hivecast build
pnpm --filter hivecast build:deb

# Install (Ubuntu/Debian). Replace <version> and <arch>.
sudo dpkg -i projects/matrix-3/packages/hivecast/native-dist/hivecast_<version>_<arch>.deb

The postinst script (build-deb-installer.js:272-401):

  1. Creates a system user/group hivecast (or binds the install to the user running sudo, when SUDO_USER is set and not root).
  2. Creates /var/lib/hivecast/ and its subtree (logs/, nats/service/, nats/service/jetstream/) with mode 0750.
  3. Writes /var/lib/hivecast/host.json (HTTP host, port 3100, NATS mode=external pointing at nats://127.0.0.1:4222, auth mode=local-client).
  4. Writes /var/lib/hivecast/nats/service/nats-server.conf (port 4222, websocket port 4223, JetStream store at /var/lib/hivecast/nats/service/jetstream).
  5. Calls hivecast seed --home /var/lib/hivecast to populate the bundled system package store.
  6. Drops /etc/systemd/system/hivecast-{nats,host}.service.d/10-workstation-user.conf to override User=/Group= if SUDO_USER is non-default.
  7. chown -R the home to the service user.
  8. Installs /etc/systemd/journald.conf.d/hivecast.conf with SystemMaxUse=2G, SystemKeepFree=4G, SystemMaxFileSize=128M, MaxFileSec=1week, RuntimeMaxUse=200M, RateLimitIntervalSec=30s, RateLimitBurst=10000. This is the journald cap added by the launch-readiness atomic-writes work (WORKSTREAMS/launch-readiness-atomic-writes-and-bootstrap/).
  9. systemctl daemon-reload, then enables and starts both services.

The two services ​

hivecast-nats.service ​

ini
[Unit]
Description=HiveCast local NATS service
After=network.target
StartLimitBurst=5
StartLimitIntervalSec=60

[Service]
Type=simple
User=hivecast
Group=hivecast
ExecStart=/opt/hivecast/dist/bin/nats-server -c /var/lib/hivecast/nats/service/nats-server.conf
Restart=on-failure
RestartSec=5s
WorkingDirectory=/var/lib/hivecast
NoNewPrivileges=true
LogRateLimitIntervalSec=10s
LogRateLimitBurst=200
MemoryHigh=512M
MemoryMax=1G
TasksMax=1024

[Install]
WantedBy=multi-user.target

Notable hardening (build-deb-installer.js:107-132):

  • StartLimitBurst=5 + StartLimitIntervalSec=60 — at most 5 starts per minute. Prevents the runaway-restart pattern that filled disks in earlier releases.
  • LogRateLimitIntervalSec=10s + LogRateLimitBurst=200 — caps NATS log emission rate at the systemd level.
  • MemoryHigh=512M, MemoryMax=1G — soft and hard memory caps.
  • NoNewPrivileges=true — even if NATS is compromised, no setuid escape.

hivecast-host.service ​

ini
[Unit]
Description=HiveCast local Host service
After=hivecast-nats.service
Requires=hivecast-nats.service
StartLimitBurst=5
StartLimitIntervalSec=60

[Service]
Type=simple
User=hivecast
Group=hivecast
ExecStart=/opt/hivecast/libexec/hivecast-host-service-run
Restart=on-failure
RestartSec=5s
WorkingDirectory=/var/lib/hivecast
Environment=MATRIX_HOME=/var/lib/hivecast
Environment=MATRIX_HOST_HOME=/var/lib/hivecast
LogRateLimitIntervalSec=10s
LogRateLimitBurst=200
MemoryHigh=1G
MemoryMax=2G
TasksMax=2048

[Install]
WantedBy=multi-user.target

Requires=hivecast-nats.service means stopping NATS stops the Host. That is intentional: the Host without its bus is a stopped Host.

The ExecStart points at a shell wrapper (build-deb-installer.js:216-270), not directly at host-service/cli.js. The wrapper:

  1. Spawns node host-service/cli.js start --home /var/lib/hivecast in the background, capturing its pid.
  2. Polls host.status.json for up to 30 seconds, waiting for the Host to become ready.
  3. Spawns hivecast bootstrap-default-runtimes --home /var/lib/hivecast in the background — up to 6 attempts, 5s apart, logging to /var/lib/hivecast/logs/host-bootstrap.log. This is the post-start hook that registers the default runtime targets if they have not yet been registered.
  4. wait on the Host pid; if SIGTERM/SIGINT arrive, kill bootstrap then the Host and exit.

Operator commands ​

bash
# Status
sudo systemctl status hivecast-host.service hivecast-nats.service

# Logs (tail with -f)
sudo journalctl -u hivecast-host.service -f
sudo journalctl -u hivecast-nats.service -f
sudo tail -f /var/lib/hivecast/logs/host-bootstrap.log

# Restart
sudo systemctl restart hivecast-host.service

# Stop without disabling
sudo systemctl stop hivecast-host.service hivecast-nats.service

# Disable (do not start at boot)
sudo systemctl disable hivecast-host.service hivecast-nats.service

# Uninstall
sudo apt remove hivecast        # leaves /var/lib/hivecast
sudo apt purge hivecast         # also removes /var/lib/hivecast and units.d overrides

The prerm / postrm scripts (build-deb-installer.js:168-196) handle stop + disable on remove and clean up the units.d overrides + journald drop-in on purge.

See also ​