Matrix Package Lifecycle

Appearance

Logs ​

Status: present state, partial. There is no hivecast logs subcommand; the wrapper's help text doesn't list one. Logs live as plain text files under the Host home (and as journald output for systemd-managed Hosts). This page documents the actual locations and the recipes operators use today.

Per-runtime logs ​

<host-home>/logs/runtimes/
├── RUNTIME-HOST-SYSTEM.stdout.log
├── RUNTIME-HOST-SYSTEM.stderr.log
├── RUNTIME-HOST-GATEWAY.stdout.log
├── RUNTIME-HOST-GATEWAY.stderr.log
├── RUNTIME-HOST-CHAT.stdout.log
└── ...

Each supervised runtime gets its own pair of log files keyed by runtime id. CLAUDE.md lists this layout under "Host state and logs":

<host-home>/host.status.json, <host-home>/runtimes/*.json, <host-home>/credentials/hivecast-link.json, <host-home>/credentials/hivecast-install.json, and <host-home>/logs/runtimes/.

To follow:

bash
tail -f <host-home>/logs/runtimes/<runtimeId>.stdout.log

To get the last N lines of a stopped runtime:

bash
tail -n 200 <host-home>/logs/runtimes/<runtimeId>.stderr.log

Host-level logs ​

For non-systemd installs, the Host process itself writes to:

<host-home>/logs/host.stdout.log
<host-home>/logs/host.stderr.log

For systemd-managed Hosts (the Ubuntu .deb installer path), use journald:

bash
journalctl -u hivecast-host.service -f      # follow
journalctl -u hivecast-host.service -n 500  # last 500 lines
journalctl -u hivecast-nats.service -f      # the sibling NATS process

NATS logs ​

The bundled NATS sibling process logs to its own data directory (declared in host.json:transport.nats.dataDir, default <host-home>/nats/host-default/):

<host-home>/nats/host-default/nats-server.log
<host-home>/nats/host-default/nats-server.pid

For systemd installs, journald: journalctl -u hivecast-nats.service -f.

Why logging happens through actorLog ​

CLAUDE.md Rule 9.4 forbids console.log in actor code. Use actorLog(). Reasons:

  1. Identity: actorLog carries the actor's mount and runtime id, so a bus-wide log stream can correlate entries.
  2. Routing: bus-native logs can be subscribed to by an operator actor (smithers, system.observability).
  3. Discipline: keeping console.log out of actor code prevents stdout pollution from breaking the runner's structured output when running with --json.

The output of actorLog ends up in stdout/stderr of the runtime, which means it ends up in <host-home>/logs/runtimes/<runtimeId>.{stdout,stderr}.log like any other runtime output.

Common log triage recipes ​

bash
# 1. Which runtime crashed?
ls -lt <host-home>/logs/runtimes/

# 2. Why did it crash?
tail -n 500 <host-home>/logs/runtimes/<runtimeId>.stderr.log | less

# 3. Did the Host see the crash?
hivecast runtimes --home <host-home> | jq '.[] | select(.runtimeId=="<runtimeId>")'

# 4. Are runtime records corrupt?
hivecast seed
# corrupt[] in the output points to zero-byte or unparseable runtime.json files

# 5. systemd-level failures
journalctl -u hivecast-host.service --since "1 hour ago"

Target state — hivecast logs ​

Status: target state.

A unified log command would aggregate Host + runtime logs through one pager and accept a runtime selector. Today the workaround is tail/journalctl per source. None of this is in code.

See also ​

Source: Log paths come from the Host config layout enforced by projects/matrix-3/packages/host-service/src/cli.ts and the runtimeStorage/logsDir fields in host.json.