Health Checks

Broch exposes two HTTP health endpoints. Both return JSON, require no authentication, and are cheap to call.

Endpoint	Probe	Returns
GET /healthz	Liveness — is the process responding?	Always 200 if the process is up
GET /healthz/ready	Readiness — are the license and auth config valid?	200 when valid, 503 otherwise

/healthz — liveness

Returns 200 as soon as the process can answer an HTTP request. It runs no checks — it does not touch the database, the license, or your IdP. If it stops returning 200, the process is wedged and should be restarted.

curl -fsS https://tunnels.example.com/healthz
# {"status":"Healthy"}

/healthz/ready — readiness

Returns 200 only when the server has a valid license and authentication configuration, 503 otherwise. The body carries the server version and each individual check:

curl -sS https://tunnels.example.com/healthz/ready

{
  "status": "Healthy",
  "version": "1.4.0",
  "duration": 12.4,
  "checks": [
    { "key": "license", "status": "Healthy", "description": "License valid — expires 2026-12-31." }
  ]
}

status is Healthy, Degraded (e.g. a license in its grace period), or Unhealthy. The broch status and broch doctor commands read this endpoint so the operator sees version and readiness together.

Which probe should gate traffic?

Gate orchestrator and load-balancer health checks on /healthz (liveness) — not /healthz/ready.

/healthz/ready is license-gated, and a freshly deployed server has no license until an admin activates one in first-run setup. If a load balancer or orchestrator withholds traffic until /healthz/ready returns 200, the server never receives the request that reaches the setup UI — a deadlock. Gate traffic on /healthz; use /healthz/ready for observability (dashboards, alerts) and the broch CLI.

Caution

Don’t point a Kubernetes readinessProbe, an AWS target-group health check, or an Azure Container Apps readiness probe at /healthz/ready. Use /healthz. Reserve /healthz/ready for monitoring and broch status / broch doctor.

First boot and the readiness lifecycle

On first boot the server has no activated license, so /healthz/ready returns 503 until setup completes. The first activation calls the Broch central server once to exchange your license key for a signed token; after that the token is cached in the database and validated locally, so readiness no longer depends on network reachability. See Licensing.

When a license later enters its grace period or is rejected, /healthz/ready reports Degraded / Unhealthy with detail in each check’s description — the same text broch status surfaces.