HiveCast Product

Appearance

Host not running ​

You ran hivecast install, you tried to use it, and something is not working at the most basic level — curl http://127.0.0.1:3100/healthz fails, hivecast status returns nothing useful, or the gateway is not serving.

This page is the triage path. Run the checks in order; the first one that fails is your problem.

Check 1 — Is the supervisor process alive? ​

bash
hivecast status --home <host-home>
OutputDiagnosisNext step
Prints a JSON status with status: "running"Supervisor is alive. The problem is downstreamSkip to Check 4
Matrix Host Service is not runningNot running. Either never started, or crashedContinue to Check 2
ECONNREFUSED against host-service socketSame as above (often, the socket file is stale)Continue to Check 2
Hangs foreverStatus file may be present but stale; supervisor crashed without clearingContinue to Check 2

Check 2 — host.status.json and host.pid ​

bash
ls -la <host-home>/host.status.json <host-home>/host.pid
cat <host-home>/host.status.json | jq .

If both files exist but the recorded pid is dead:

bash
cat <host-home>/host.pid       # 12345
ps -p 12345                    # nothing prints

…the supervisor crashed and left stale state. Just running hivecast start again will overwrite both. The next start clears the stale host.status.json (because step 1 of startHostProduct checks isProcessAlive(pid) before short-circuiting — hivecast.mjs:1471).

Check 3 — Is NATS running? ​

bash
ls -la <host-home>/nats/host-default/nats-server.pid
cat <host-home>/nats/host-default/nats-server.pid       # 67890
ps -p 67890                                              # should show nats-server

If the pidfile exists but the process is dead:

bash
rm <host-home>/nats/host-default/nats-server.pid
hivecast start --home <host-home>

If the pidfile is missing entirely, hivecast start will spawn a fresh NATS sibling. If you keep getting nats-server: bind: address already in use, see NATS connection failed → Port already in use.

On .deb-managed installs, systemctl status hivecast-nats.service is the equivalent check.

Check 4 — Are the runtimes registered but failed? ​

bash
hivecast runtimes --home <host-home>

If the supervisor is up but every runtime shows status: "failed" or status: "stopped", that's a runtime-spawn problem, not a Host problem. See Package failed to start.

If the gateway runtime specifically is failed, you'll get the "Host is up but no HTTP" symptom. Tail its log:

bash
tail -100 <host-home>/logs/runtimes/RUNTIME-HOST-LOCAL-*-GATEWAY.stderr.log

Common causes: HTTP port already in use, gateway runtime crashed during bootstrap.

Check 5 — hivecast doctor ​

bash
hivecast doctor --home <host-home> --repair

The --repair flag attempts auto-fix where it can. The output enumerates each check's pass/fail status. See CLI → hivecast doctor.

Check 6 — Verify the install isn't broken ​

bash
ls -la <host-home>/bin/nats-server*
ls -la <host-home>/host.json
ls -la <host-home>/packages/global/node_modules/@open-matrix/matrix-edge/

If any of these are missing, the install is incomplete. Re-run:

bash
hivecast install --home <host-home> --no-start

--no-start lays out files without starting; check for errors in the output JSON. Then hivecast start --home <host-home> separately.

Common scenarios ​

"I rebooted and the Host doesn't auto-start" ​

  • .deb install → sudo systemctl status hivecast-host.service. If inactive (dead), run sudo systemctl start hivecast-host.service. If still failing, sudo journalctl -u hivecast-host.service -n 100.
  • Source-checkout install → no auto-start. Run hivecast start --home <host-home> manually.

"I ran hivecast install and it printed installed: true, started: true but nothing's running" ​

The install JSON output is what installHostProduct returns. If start.ok is false somewhere in the nested object, start did fail. Check the embedded start object's error fields. Re-run with --no-start, then hivecast start --home <host-home> for clearer error reporting.

"I'm getting Host Service CLI not found in HiveCast package" ​

The bundled CLI is missing. This means the wrapper itself is broken (incomplete dist/). Re-build:

bash
pnpm --filter hivecast build

If using a release tarball, re-extract.

"I'm getting Packaged nats-server binary was not installed into the Host home" ​

The bundled NATS binary is missing from the home. assertHostProductInstallable (hivecast.mjs:749-761) checks for it. The install step should have copied it from dist/bin/nats-server[.exe] — if that's missing, the wrapper build is incomplete.

"I'm getting weird EBADF or ENOENT mid-start" ​

Almost always a stale state directory. The cleanest reset:

bash
hivecast stop --home <host-home>          # in case anything's actually running
rm -f <host-home>/host.status.json <host-home>/host.pid
rm -f <host-home>/nats/host-default/nats-server.pid
hivecast start --home <host-home>

This does NOT touch runtimes/, credentials/, or host.json. Safe to run.

See also ​

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 763-771 (readHostStatus) and 1464-1509 (startHostProduct short-circuit logic).