Collect diagnostics

Before filing an issue, capture state. The triager needs the same information you'd want — JSON state, log slices, and the surface area of what was attempted. This page is the recipe.

The minimum bundle

Five files. Capture them in this order so each one's timestamp is meaningful:

HOME_DIR=/tmp/matrix-home   # change to your <host-home>
OUT=/tmp/hivecast-diag-$(date +%Y%m%d-%H%M%S)
mkdir -p "$OUT"

# 1. doctor JSON — the canonical health snapshot
hivecast doctor --home "$HOME_DIR" --json > "$OUT/doctor.json" 2>&1
echo $? > "$OUT/doctor.exit"

# 2. status JSON
hivecast status --home "$HOME_DIR" > "$OUT/status.json" 2>&1
echo $? > "$OUT/status.exit"

# 3. runtimes JSON
hivecast runtimes --home "$HOME_DIR" > "$OUT/runtimes.json" 2>&1
echo $? > "$OUT/runtimes.exit"

# 4. seed (reports runtime record health honestly)
hivecast seed --home "$HOME_DIR" > "$OUT/seed.json" 2>&1
echo $? > "$OUT/seed.exit"

# 5. config + a slice of host.status.json
cp "$HOME_DIR/host.json" "$OUT/host.json" 2>/dev/null || true
cp "$HOME_DIR/host.status.json" "$OUT/host.status.json" 2>/dev/null || true

# Bundle it
tar czf "$OUT.tar.gz" -C "$(dirname "$OUT")" "$(basename "$OUT")"
echo "Wrote $OUT.tar.gz"

Add log slices

# Last 500 lines of the Host's stdout/stderr
tail -500 "$HOME_DIR/logs/host.stdout.log" > "$OUT/host.stdout.tail.log" 2>/dev/null
tail -500 "$HOME_DIR/logs/host.stderr.log" > "$OUT/host.stderr.tail.log" 2>/dev/null

# Last 500 lines of NATS
tail -500 "$HOME_DIR/logs/nats.stdout.log" > "$OUT/nats.stdout.tail.log" 2>/dev/null
tail -500 "$HOME_DIR/logs/nats.stderr.log" > "$OUT/nats.stderr.tail.log" 2>/dev/null

# Last 200 lines of every runtime's stderr
mkdir -p "$OUT/runtimes-stderr"
for f in "$HOME_DIR"/logs/runtimes/*.stderr.log; do
  [ -f "$f" ] || continue
  tail -200 "$f" > "$OUT/runtimes-stderr/$(basename "$f")"
done

# Re-bundle
tar czf "$OUT.tar.gz" -C "$(dirname "$OUT")" "$(basename "$OUT")"

On .deb-managed installs

Add the systemd journal:

sudo journalctl -u hivecast-host.service --since "1 hour ago" > "$OUT/journal-host.log"
sudo journalctl -u hivecast-nats.service --since "1 hour ago" > "$OUT/journal-nats.log"
sudo systemctl status hivecast-host.service > "$OUT/systemctl-status-host.txt"
sudo systemctl status hivecast-nats.service > "$OUT/systemctl-status-nats.txt"

# Bootstrap shim log
cp /var/lib/hivecast/logs/host-bootstrap.log "$OUT/host-bootstrap.log" 2>/dev/null || true

What hivecast doctor --json produces

From runHostDoctor (hivecast.mjs:1031-1187), the output is:

{
  "ok": true|false,
  "home": "<host-home>",
  "origin": "http://127.0.0.1:3100",
  "checks": [
    { "name": "<check>", "ok": true|false, "detail": "...", "remedy": "..." },
    ...
  ],
  "logs": [
    "<host-home>/logs/host.stdout.log",
    "<host-home>/logs/host.stderr.log",
    "<host-home>/logs/runtimes"
  ]
}

Checks include:

• host.status.json present and parseable
• Host process is alive
• bundled NATS binary present and executable
• <host-home>/credentials/hivecast-install.json valid
• runtime records: healthy / corrupt count
• duplicate live runtime claims
• root collision guard (any wire-root mismatch across host.json, host.status.json, hivecast-link.json, runtime records)
• (with --cloud) matrix-web route returns 200
• (with --cloud) google login redirect
• (with --cloud) google oauth state persistence

The remedy field on each check tells the triager (or you) what to try.

Sensitive data warning

The diagnostic bundle CAN include sensitive information if you don't filter:

File	Contains	Treat as
host.json	auth.sessionSecret if set	secret
<host-home>/credentials/hivecast-link.json	per-Device NATS JWT, link record	secret
<host-home>/credentials/hivecast-install.json	installId	semi-secret
<host-home>/credentials/factotum/*	inference provider tokens	very secret
journald logs	varies	check before sharing

The recipe above does NOT include credentials/ — by design. Do not add credentials/ to a diagnostic bundle that you share with anyone. Per CLAUDE.md: "Inference credentials NEVER leave the local machine."

If host.json has a session secret in it, redact:

jq 'del(.auth.sessionSecret)' "$HOME_DIR/host.json" > "$OUT/host.json"

What NOT to capture

• The full contents of <host-home>/nats/host-default/jetstream/ — JetStream message streams may contain user data.
• The full contents of <host-home>/credentials/ — per the warning above.
• The full contents of <host-home>/runtimes/<id>/ BEYOND runtime.json — per-runtime auxiliary state may include cached data.

Filing an issue

When filing:

• Attach the .tar.gz.
• State which install path (.deb / source-checkout / npm-global / Docker).
• State the wrapper version: cat /opt/hivecast/package.json | jq -r .version or cat projects/matrix-3/packages/hivecast/package.json | jq -r .version.
• State the OS: uname -a.
• State the symptom in one sentence and the steps to reproduce in 3-5 lines.

See also

• Host not running, NATS connection failed, Package failed to start, Device pairing failed, Permission denied — symptom-driven recipes.
• CLI → exit codes and diagnostics — error message catalogue.
• Local Device → Logs — log file inventory.

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 1031-1187 (runHostDoctor and the check list).