Runtime Host

Appearance

Service install ​

A "service install" supervises the Host through the operating system's native service manager so that:

  • The Host starts on machine boot.
  • The Host restarts on crash, with a configured rate limit.
  • A dedicated unprivileged service account owns the Host's home directory.
  • Logs go through the OS log system (journald on Linux), with disk caps enforced.
  • Uninstall is a documented OS operation (apt remove hivecast on Debian).

Present state — Linux only ​

Today exactly one platform has a real service install: Debian/Ubuntu via the .deb package.

The .deb is built by projects/matrix-3/packages/hivecast/scripts/build-deb-installer.js. It ships:

  • /opt/hivecast/ — the wrapper, the host-service distribution, the bundled NATS binary, a vendored Node runtime, and npm/npx shims.
  • /usr/bin/hivecast, /usr/bin/matrix — public CLI entry points that exec the bundled Node against the bundled scripts.
  • /lib/systemd/system/hivecast-nats.service — supervises NATS as a long-running service under user hivecast.
  • /lib/systemd/system/hivecast-host.service — supervises the host-service with Requires=hivecast-nats.service, so the Host cannot start without NATS.
  • /var/lib/hivecast/ — the Host home, owned by service user hivecast (or by ${SUDO_USER} if the package is being installed via sudo so a workstation user gets the install bound to their own UID).

See Linux systemd for the full flow, what the postinst generates, and the unit hardening.

Target state — macOS launchd ​

Not yet shipped. Target work is filed as P1.16b in the launch backlog. A target-state installer would generate per-user LaunchAgent plist files (or a system LaunchDaemon for shared workstations) wrapping hivecast start --home <home>. See macOS launchd.

For now, on macOS use the Local install. It works identically to Linux local install; you just have to start it manually after each reboot or wire it to your own launchctl plist.

Target state — Windows Service ​

Not yet shipped. Target work is also filed as P1.16b. A target-state installer would register a Windows Service that runs node hivecast.mjs start --home <home> under a chosen account and survives reboot. See Windows Service.

For now, on Windows use the Local install. The Host binary's windowsHide: true runtime spawn is wired correctly, so you do not get one console window per supervised runtime (projects/matrix-3/packages/host-service/src/matrix-host-service.ts:380-395).

What "service install" implies for design ​

A service install moves three responsibilities from the Host code to the OS:

  1. Crash recovery. systemd's Restart=on-failure restarts the Host on exit. The Host code does not need to relaunch itself.
  2. Boot start. WantedBy=multi-user.target in the unit file asks systemd to start the Host at boot.
  3. Log rotation. journald, with the cap installed by the postinst (see Linux systemd — SystemMaxUse=2G, SystemKeepFree=4G), prevents a runaway log emitter from filling the disk. The launch-readiness work made this hardening real (see WORKSTREAMS/launch-readiness-atomic-writes-and-bootstrap/).

The Host code still owns its own parse-and-skip recovery for corrupt runtime records (atomic-write code in projects/matrix-3/packages/host-service/src/util/atomic-write.ts and HostStateStore.listRuntimeRecordsAndCorrupt at host-state-store.ts:106-142). These two layers compose: even if a runtime record is corrupt and the Host bootstrap logs the corruption, systemd keeps the Host alive and the journald cap keeps logs bounded.

See also ​