Logs

The Host writes logs to two places: per-process files under <host-home>/logs/ and (on .deb-managed installs) the systemd journal. This page maps every log surface, what to look for, and how to tail.

Inventory

File / source	Written by	What's in it
<host-home>/logs/host.stdout.log	host-service supervisor	Standard output of the supervisor process
<host-home>/logs/host.stderr.log	host-service supervisor	Standard error — fatal errors, stack traces
<host-home>/logs/nats.stdout.log	bundled NATS	Standard output of the NATS sibling process
<host-home>/logs/nats.stderr.log	bundled NATS	Standard error of NATS — bind failures, JetStream errors
<host-home>/logs/runtimes/<runtime-id>.stdout.log	per-runtime spawn	Standard output of one runtime
<host-home>/logs/runtimes/<runtime-id>.stderr.log	per-runtime spawn	Standard error of one runtime
<host-home>/logs/host-bootstrap.log	systemd ExecStart shim	bootstrap-default-runtimes output (.deb only)
journalctl -u hivecast-host.service	systemd	Captures host.{stdout,stderr}.log on systemd-managed Hosts
journalctl -u hivecast-nats.service	systemd	Captures nats.{stdout,stderr}.log on systemd-managed Hosts

The host-service stdout/stderr files are opened in startHostProduct (hivecast.mjs:1486-1487):

const stdout = openSync(join(matrixHome, 'logs', 'host.stdout.log'), 'a');
const stderr = openSync(join(matrixHome, 'logs', 'host.stderr.log'), 'a');

The NATS sibling's outputs are opened in startNatsSibling (hivecast.mjs:663-665).

Tailing

Source-checkout / non-systemd install

# Host supervisor
tail -f <host-home>/logs/host.stderr.log

# NATS broker
tail -f <host-home>/logs/nats.stderr.log

# One runtime
tail -f <host-home>/logs/runtimes/RUNTIME-HOST-LOCAL-XXXX-DIRECTOR.stderr.log

# All runtimes (limited)
tail -f <host-home>/logs/runtimes/*.stderr.log

The files are append-only and never truncated by the wrapper. Rotate manually if size becomes an issue.

.deb / systemd install

# Host
sudo journalctl -u hivecast-host.service -f

# NATS
sudo journalctl -u hivecast-nats.service -f

# Both since boot
sudo journalctl -u hivecast-host.service -u hivecast-nats.service --since "1 hour ago"

# Bootstrap shim output (separate file under /var/lib/hivecast)
tail -f /var/lib/hivecast/logs/host-bootstrap.log

# Per-runtime files (still per-runtime files, even on .deb)
tail -f /var/lib/hivecast/logs/runtimes/RUNTIME-HOST-LOCAL-XXXX-DIRECTOR.stderr.log

Note: even on .deb installs, per-runtime logs go to files, not the journal. Each runtime is spawned with stdio redirected to <host-home>/logs/runtimes/<id>.{stdout,stderr}.log. Only the supervisor and NATS itself are journal-backed.

Journald hardening (.deb only)

The postinst script writes /etc/systemd/journald.conf.d/hivecast.conf (scripts/build-deb-installer.js:368-388):

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

SystemMaxUse=2G caps total journald usage at 2 GB. Without this, a runaway log emitter could fill /var before rotation kicks in. The unit files also set LogRateLimitIntervalSec=10s + LogRateLimitBurst=200 per service, so each one is bounded at 200 messages per 10 seconds at the systemd layer.

RateLimitIntervalSec=30s + RateLimitBurst=10000 are the global journald rate limits — large enough that healthy traffic is never throttled, small enough to bound a fault.

What to look for

When something doesn't work, the logs to read are typically (in order):

1. host.stderr.log / journalctl -u hivecast-host.service — supervisor errors. "did host-service start? did it crash? did a runtime spawn fail to register?"
2. <runtime-id>.stderr.log — runtime-specific errors. "did this particular runtime crash on its own bootstrap, or fail to mount its actor, or fail to bind a port?"
3. nats.stderr.log / journalctl -u hivecast-nats.service — NATS errors. Almost always: bind failure, JetStream storage error, config syntax error.
4. host-bootstrap.log (.deb only) — bootstrap shim errors. "did the post-start runtime registration step succeed?"

A fresh-clone bootstrap that doesn't reach the dashboard typically has the answer in the gateway runtime's stderr (RUNTIME-HOST-LOCAL-...-GATEWAY.stderr.log).

Common log signatures

Log line (verbatim)	Meaning
Failed to parse runtime.json: Unexpected end of JSON input	A runtime record is zero-byte. Bootstrap parses-and-skips; hivecast seed reports it; hivecast start self-heals
nats: Listen on 127.0.0.1:4222: address already in use	Another NATS or another process is on the port. Check lsof -i :4222; pin a different port with --port
EADDRINUSE: address already in use 0.0.0.0:3100	The gateway can't bind. Reuse --http-port or stop the other process
Matrix Host Service exited before writing running status	The supervisor crashed during start. Look at host.stderr.log
Host Service command exited with signal SIGTERM	A delegated up/down/invoke was killed externally
Timed out waiting for Matrix Host Service to start	The supervisor took >15s to write host.status.json. Typically a bigger problem upstream — check host.stderr.log

For the full common-error catalogue, see CLI → exit codes and diagnostics.

See also

• Runtime records — read a runtime's runtime.json alongside its log file for full context.
• Troubleshooting → Collect diagnostics — hivecast doctor --json plus log slices in one bundle.
• Reference → Service manager integration — the journald hardening above.

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 663-665 (NATS log file open) and 1486-1487 (host-service log file open); projects/matrix-3/packages/hivecast/scripts/build-deb-installer.js lines 368-388 (journald conf).