Skip to content
broch
get started →

Health Checks

Broch exposes three HTTP health endpoints. All 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 — is the license valid and the database reachable? 200 when Healthy or Degraded, 503 when Unhealthy
GET /healthz/diagnostics Advisory — is the wildcard DNS set up? 200; status is Degraded at worst, and never affects readiness

/healthz — Liveness

Section titled “/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.

Terminal window
curl -fsS https://broch.{your-domain}/healthz
# {"status":"Healthy"}

/healthz/ready — Readiness

Section titled “/healthz/ready — Readiness”

Checks the license and the database. The body carries the server version and each check:

Terminal window
curl -sS https://broch.{your-domain}/healthz/ready
{
  "status": "Healthy",
  "version": "1.35.0",
  "duration": 12.4,
  "checks": [
    { "key": "license", "status": "Healthy", "description": "License valid — expires 2026-12-31." },
    { "key": "database", "status": "Healthy", "description": "Database reachable." }
  ]
}

status is Healthy, Degraded or Unhealthy. Degraded still returns 200, and it covers a database Broch can’t reach as well as a license in its grace period, so alert on the status field, not the HTTP code. The broch status and broch doctor commands read this endpoint so the operator sees version and readiness together.

Authentication settings aren’t checked here. Broch refuses to start when a required identity provider value is missing, so that shows up as a server that never answers; a wrong value, such as a bad secret, shows up only at sign-in.

/healthz/diagnostics — Wildcard DNS

Section titled “/healthz/diagnostics — Wildcard DNS”

Reports whether the wildcard DNS for tunnel URLs is set up, with what to fix in each check’s description. It’s advisory: a misconfigured tunnel domain doesn’t stop the server serving everything else, so it never affects readiness.

Which Probe Should Gate Traffic?

Section titled “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 at first sign-in. If a load balancer or orchestrator withholds traffic until /healthz/ready returns 200, the server never receives the request that reaches setup, so setup can’t finish. Gate traffic on /healthz; use /healthz/ready for observability (dashboards, alerts) and the broch CLI.

First Boot and the Readiness Lifecycle

Section titled “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 doesn’t depend on reaching the central server. See Licensing & Billing.

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.

Client Version Policy

Section titled “Client Version Policy”

GET /api/configuration returns the version policy the CLI and web app check for compatibility. It isn’t a health check.

PrivacyTerms