Health checks

A process declares checks under spec.health, one entry per name:

kind: process
name: api
spec:
  cmd: cargo
  args: [run, -p, api]
  health:
    web:
      http: { port: 8101, path: /health }
      initial_delay: 2
      period: 1
      timeout: 5
      failures: 60
    db:
      exec: { cmd: ./scripts/db-ready.sh }
      period: 10

A check

Each check has exactly one probe and a schedule:

probe	passes when	fields
`http`	a `GET http://<host>:<port><path>` answers 2xx or 3xx	`host` (`localhost`), `port`, `path` (`/`)
`tcp`	a connect to `<host>:<port>` succeeds	`host` (`localhost`), `port`
`exec`	the command exits 0	`cmd`, `args`, `cwd` (the process’s, relative to the workspace), `env` (merged over the process’s)

field		default
`initial_delay`	seconds after each start before the first attempt	`0`
`period`	seconds between attempts	`5`
`timeout`	seconds an attempt may take	`5`
`failures`	consecutive failures that stop the process as a failed exit	none

port may be an expression over a port: http: { port: "${ port.web.status.value }" }.

What it publishes

Every start of the child starts every check after its initial_delay; they run every period for the life of that child. The status carries one entry per check:

{
  "healthy": false,
  "health": {
    "web": { "ok": true, "failures": 0, "checked_at": 1762070005000 },
    "db":  { "ok": false, "failures": 3, "checked_at": 1762070004000, "error": "exit status 1" }
  }
}

failures counts failures in a row since the last pass or the child’s start, checked_at is the last attempt (null before the first), error says why it failed. healthy is true while the process runs and every check passes; a process without checks is healthy exactly while running. Both reset when the child exits. runy ps shows running healthy or running unhealthy; the journal logs a check’s first result and each change between passing and failing, not every attempt.

Gating dependents

A reader waits on a check through needs:

kind: process
name: client
needs: ['${ process.api.status.health.web.ok }']
spec: { cmd: pnpm, args: [dev] }

The client is Pending until the API’s web check passes. If the check fails later the client goes Pending again and keeps running.

Restarting on failure

With failures: N a check that fails N times in a row stops the child as a failed exit, logs why, and the process’s restart policy decides what follows. on: failure restarts it; never leaves it failed. Without failures a failing check only reports.