Health Checks

Health checks let CMDHub verify that a service is actually ready to accept traffic - not just that its process started. Without a health check, a service transitions to running as soon as the process launches.

Check types

HTTP

Sends a GET request to a URL and expects a 2xx response.

"healthCheck": {
  "type": "http",
  "target": "http://localhost:3000/healthz",
  "interval": 5,
  "timeout": 3
}

Use this for HTTP/HTTPS services. Any 2xx status code counts as healthy. A connection error, timeout, or non-2xx response marks the service unhealthy.

TCP

Opens a TCP connection to a host:port and expects it to succeed.

"healthCheck": {
  "type": "tcp",
  "target": "localhost:5432",
  "interval": 5,
  "timeout": 3
}

Use this for services that don’t speak HTTP - databases, caches, message brokers. As long as the port accepts a connection, the service is considered healthy.

Shell

Runs a shell command and expects it to exit with code 0.

"healthCheck": {
  "type": "shell",
  "target": "pg_isready -h localhost -p 5432",
  "interval": 10,
  "timeout": 5
}

Use this when you need a richer check - for example, running a database client command, checking a file exists, or querying an API with curl.

Configuration fields

Field	Default	Description
`type`	-	`http`, `tcp`, or `shell`
`target`	-	URL, `host:port`, or shell command
`interval`	`5`	Seconds between checks while the service is running
`timeout`	`3`	Seconds before a check attempt is considered failed

Status indicators

The indicator next to each service name in the popover reflects the health check result:

Color	Meaning
Green	Running and healthy
Orange	Running but health check is failing (unhealthy)
Red	Process has crashed
Grey	Stopped

During startup the indicator pulses while CMDHub waits for the first successful check.

Health checks and dependencies

When a service has dependencies, CMDHub waits for each dependency’s health check to pass before starting the next tier. If a dependency never becomes healthy within a startup timeout, the dependent service is not started.

See Services → Dependencies for more detail.