Service manager integration

Today, only Linux (systemd) is fully shipped. macOS (launchd) and Windows (Service) installers exist as scripts but are not yet released. This page documents what's shipped and what's planned.

Linux — systemd (shipped)

The .deb installs two units: hivecast-nats.service and hivecast-host.service. Both are written by scripts/build-deb-installer.js:104-162.

hivecast-nats.service

[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

Directive	Reason
After=network.target	NATS needs the network up
StartLimitBurst=5, StartLimitIntervalSec=60	Stop trying after 5 failures in 60s — prevents tight crash-loop
Restart=on-failure, RestartSec=5s	Auto-restart on crash with 5s backoff
NoNewPrivileges=true	Hardening
LogRateLimitBurst=200	Cap log flood at 200 msgs / 10s
MemoryHigh=512M, MemoryMax=1G	Memory accounting + cap
TasksMax=1024	Bound thread/process count

hivecast-host.service

[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

Directive	Reason
After=hivecast-nats.service	Wait for NATS to be up
Requires=hivecast-nats.service	NATS is a hard dependency
Environment=MATRIX_HOME=..., Environment=MATRIX_HOST_HOME=...	Set both env vars systemd-side
Same hardening + accounting	Mirrored from NATS unit

The ExecStart script /opt/hivecast/libexec/hivecast-host-service-run runs host-service AND, after the supervisor reports healthy, runs hivecast bootstrap-default-runtimes. Source scripts/build-deb-installer.js:216-270.

Workstation-user drop-in

The postinst writes (when invoked via sudo by a real user):

# /etc/systemd/system/hivecast-nats.service.d/10-workstation-user.conf
[Service]
User=<sudo_user>
Group=<sudo_user_primary_group>

Same for hivecast-host.service.d/10-workstation-user.conf. This makes services run as the workstation user, not the hivecast system user.

Journald hardening

The postinst writes /etc/systemd/journald.conf.d/hivecast.conf:

[Journal]
Storage=persistent
SystemMaxUse=2G
SystemKeepFree=4G
SystemMaxFileSize=128M
MaxFileSec=1week
RuntimeMaxUse=200M
ForwardToSyslog=no
RateLimitIntervalSec=30s
RateLimitBurst=10000

SystemMaxUse=2G is the disk-fill protection. Without this, a runaway log emitter could fill /var before rotation.

Operating systemctl

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

# Start/stop/restart
sudo systemctl start hivecast-host.service hivecast-nats.service
sudo systemctl stop hivecast-host.service hivecast-nats.service
sudo systemctl restart hivecast-host.service       # NATS stays up

# Logs
sudo journalctl -u hivecast-host.service -f
sudo journalctl -u hivecast-nats.service -f

# Enable/disable on boot
sudo systemctl enable hivecast-host.service hivecast-nats.service
sudo systemctl disable hivecast-host.service hivecast-nats.service

# Force recreate of unit-state
sudo systemctl daemon-reload

macOS — launchd (target state)

scripts/build-macos-pkg-installer.js exists but is not yet a regular release artifact. Target shape:

• ~/Library/LaunchAgents/ai.hivecast.host.plist — host-service unit
• ~/Library/LaunchAgents/ai.hivecast.nats.plist — NATS unit
• launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.hivecast.host.plist
• launchctl kickstart -k gui/$(id -u)/ai.hivecast.host for restart
• ~/Library/Logs/HiveCast/host.{stdout,stderr}.log for log capture

Until shipped, on macOS use the source-checkout install path and run hivecast start from a shell (or wire into a login item / shell startup).

Windows — Service (target state)

scripts/build-windows-msi-installer.js exists. Target shape:

• Native Windows Service: "HiveCast Host", "HiveCast NATS"
• sc query "HiveCast Host", Restart-Service for control
• Event Log integration for journald-equivalent log capture
• Auto-start on Windows boot

Until shipped, on Windows use the source-checkout install path and run hivecast start from a PowerShell session, or wire into Task Scheduler manually.

Cross-platform pattern

All three service-manager integrations share the same core invariants:

• Two services: NATS broker and Host supervisor.
• Hard dependency: Host requires NATS up first.
• Auto-restart on crash with backoff.
• Restart-storm protection (cap retries within an interval).
• Memory and task accounting limits.
• Persistent log capture.

The .deb installer is the reference implementation. The macOS and Windows scripts mirror its behaviour into platform-native primitives.

Why a separate hivecast-nats.service (instead of supervised by host-service)

Per the comment block in hivecast.mjs:561-582:

Why: production runs nats-server and host-service as TWO separate systemd services (.deb installer drops hivecast-nats.service + hivecast-host.service). They have independent lifecycles — restarting host-service does NOT restart NATS, and vice versa. The npm-install dev path used to spawn NATS as a child of host-service (parent/child supervised), which was wrong-shaped: a host crash took NATS down, and the coupled spawn had Windows-specific bugs that made the dev loop unreliable.

The dev wrapper now mirrors the production split: NATS is a detached sibling, host-service is external-mode-configured to connect to it. Same model both places.

See also

• Local Device → Service install — operational walk-through.
• Local Device → Logs — journalctl recipes.
• Filesystem layout — paths the units reference.
• Troubleshooting → Host not running.

Source: projects/matrix-3/packages/hivecast/scripts/build-deb-installer.js lines 104-401; projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 561-582 (sibling-NATS rationale).