Health API

The Health API provides an unauthenticated endpoint for monitoring server status and bundle health. Use this endpoint in load balancer health checks, monitoring dashboards, and alerting systems.

Note

The health endpoint is unauthenticated. It works regardless of whether NB_API_KEY is set.

GET /v1/health

Check overall server health and get a summary of bundle states.

Response:

{
  "status": "ok",
  "uptime": 3600,
  "bundles": [
    { "name": "bash", "state": "running" },
    { "name": "weather", "state": "running" },
    { "name": "postgres", "state": "crashed" }
  ]
}

Field	Type	Description
status	string	Always "ok" if the server is responding
uptime	number	Server uptime in seconds
bundles	array	Summary of each bundle’s name and state

Each bundle entry:

Field	Type	Description
name	string	Short server name
state	string	Lifecycle state: starting, running, crashed, dead, stopped

Example:

curl

curl http://localhost:27247/v1/health

Response

{
  "status": "ok",
  "uptime": 3600,
  "bundles": [
    { "name": "bash", "state": "running" },
    { "name": "weather", "state": "running" }
  ]
}

Health Check Patterns

Load Balancer

Use GET /v1/health as a lightweight liveness probe:

# Returns 200 if the server is running
curl -f http://localhost:27247/v1/health

Kubernetes

Configure liveness and readiness probes:

livenessProbe:
  httpGet:
    path: /v1/health
    port: 27247
  initialDelaySeconds: 5
  periodSeconds: 30
readinessProbe:
  httpGet:
    path: /v1/health
    port: 27247
  initialDelaySeconds: 3
  periodSeconds: 10

Monitoring

Poll GET /v1/health to track bundle stability over time. Persistent crashed or dead states in the bundles array indicate bundles that need attention. For detailed bundle inspection, use the nb__status tool with scope: "bundles".