Health

GET /healthz is the gateway's liveness probe. It is the first endpoint checked in _dispatch (right after pathname normalization), so it is unaffected by route configuration or runtime state.

Endpoint

GET /healthz
Accept: application/json

No authentication. Always returns JSON.

Response

json

{
  "ok": true,
  "status": "ok",
  "releaseVersion": "0.1.24",
  "releaseCommit": "abc1234",
  "releasePath": "/home/ubuntu/hivecast/releases/hivecast-0.1.24-abc1234/lib/node_modules/hivecast"
}

The releaseVersion / releaseCommit / releasePath fields are present when the gateway can identify itself as part of a versioned hivecast release. They come from either:

Environment variables (HIVECAST_RELEASE_VERSION, HIVECAST_RELEASE_COMMIT, HIVECAST_RELEASE_PATH).
Pattern-matching on the runtime path (.../releases/hivecast-<version>-<commit>/lib/node_modules/hivecast) per HIVECAST_RELEASE_DIR_PATTERN in projects/matrix-3/packages/system-gateway-http/src/release-metadata.ts:4.

If neither path identifies the release, those fields are absent. The response still returns { ok: true, status }.

What `/healthz` actually checks

Today: only that the HTTP listener is accepting connections and the gateway process is running. Specifically, it does NOT check:

NATS connectivity (the gateway's bus client may be disconnected and /healthz still returns ok).
Whether system.runtimes is reachable.
Whether any package runtime is healthy.
Whether system.gateway.http actor is mounted.
TLS certificate validity (Caddy owns that).

This is intentional: /healthz is a process-liveness check. Deeper checks should use specific endpoints (/api/status, system.catalog.list).

Status field

The status field today is always "ok" when the response is returned. Per buildHealthPayload:

typescript

// release-metadata.ts:12-21
export function buildHealthPayload(status: string): Record<string, unknown> {
  const release = readReleaseMetadata();
  return {
    ok: true,
    status,
    ...(release.releaseVersion ? { releaseVersion: release.releaseVersion } : {}),
    ...(release.releaseCommit ? { releaseCommit: release.releaseCommit } : {}),
    ...(release.releasePath ? { releasePath: release.releasePath } : {}),
  };
}

The handler in host-http-runtime.ts calls buildHealthPayload('ok'). A future revision may distinguish "starting", "running", "degraded" states; today only "ok" is emitted.

Wiring to monitoring

Probe type	Recommended endpoint
Process liveness (Kubernetes liveness, systemd)	`/healthz` (200 = alive)
Application readiness (Kubernetes readiness, load balancer)	`/api/status` (richer signal)
Deep introspection (operator dashboards)	`system.catalog.catalog.list` over NATS, or `/api/runtimes`

Sample systemd unit excerpt (cloud production):

ini

[Service]
Type=simple
ExecStart=/usr/bin/node /home/ubuntu/hivecast/releases/<version>/.../host-http-runtime.js
Restart=on-failure
RestartPreventExitStatus=64 65 78
WatchdogSec=30

Caddy can also be configured to health-check the gateway:

caddyfile

hivecast.ai {
  reverse_proxy localhost:3198 {
    health_uri /healthz
    health_interval 10s
    health_timeout 5s
  }
}

When `/healthz` returns 5xx

If /healthz returns 500, the gateway process is up but something failed in the response build (rare). If /healthz connection-refuses, the gateway process is down.

A 502 from a fronting Caddy layer means Caddy reached the upstream and the upstream errored or didn't respond. If Caddy is healthy and /healthz responds, the gateway is fine; the issue is elsewhere.

Release identification

The releaseCommit field is the most useful for "which version is running?" debugging. In a hivecast .deb install, the path embeds both version and commit:

/home/ubuntu/hivecast/releases/hivecast-0.1.24-abc1234/...
                                          ↑          ↑
                                       version    commit (7-40 hex chars)

hivecast doctor and other operator tools cross-reference this against the install manifest.

Health ​

Endpoint ​

Response ​

What /healthz actually checks ​

Status field ​

Wiring to monitoring ​

When /healthz returns 5xx ​

Release identification ​

See also ​