Skip to main content

GET /health

Returns the runtime health status. No authentication required.
curl http://localhost:3000/health

Response schema

{
  "status": "ok",
  "runtimeVersion": "1.0.0",
  "runtimeHash": "sha256:a3f8d2...",
  "verification": "ok",
  "audit_db": true,
  "signing_mode": "env",
  "capabilities": ["execute", "verify", "audit"],
  "supportedSchemaVersions": ["1.0.0"]
}
FieldTypeDescription
statusstring"ok" when the runtime is healthy
runtimeVersionstringSemver version of the running server
runtimeHashstringContent hash of the server binary — matches the runtimeHash in attestations
verificationstring"ok" when the signing key and verifier are configured correctly
audit_dbbooleantrue when Postgres is connected and schema is initialized
signing_mode"env" | "disk"How the signing key was loaded
capabilitiesstring[]Active capabilities — subset of ["execute", "verify", "audit"]
supportedSchemaVersionsstring[]Policy schema versions this runtime accepts

Interpreting the response

ConditionMeaning
status !== "ok"Runtime is not healthy — do not send execution requests
audit_db: falsePostgres is not connected — audit records will not be persisted
verification !== "ok"Signing or verification is misconfigured — executions will fail with 503
Non-200 responseServer is unreachable

Docker Compose health check

Add a Compose-level health check to the server service to enable dependent service health gating:
server:
  # ... existing config ...
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
    interval: 15s
    timeout: 5s
    retries: 3
    start_period: 20s

Kubernetes liveness and readiness probes

livenessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 20
  periodSeconds: 15
  timeoutSeconds: 5
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 10
  periodSeconds: 10
  timeoutSeconds: 3
  failureThreshold: 2
For stricter readiness — only mark ready when Postgres is also connected — check the response body:
readinessProbe:
  exec:
    command:
      - sh
      - -c
      - "curl -sf http://localhost:3000/health | grep -q '\"audit_db\":true'"
  initialDelaySeconds: 10
  periodSeconds: 10

Uptime monitoring

Poll /health every 30–60 seconds from your uptime monitor. Alert on:
  • Non-200 HTTP status
  • status !== "ok"
  • audit_db: false (sustained for more than one check interval)
Example shell health check script:
#!/bin/bash
HEALTH=$(curl -sf http://localhost:3000/health)
if [ $? -ne 0 ]; then
  echo "CRITICAL: Parmana server unreachable"
  exit 2
fi

STATUS=$(echo "$HEALTH" | jq -r '.status')
AUDIT=$(echo "$HEALTH" | jq -r '.audit_db')

if [ "$STATUS" != "ok" ]; then
  echo "CRITICAL: Parmana runtime status is $STATUS"
  exit 2
fi

if [ "$AUDIT" != "true" ]; then
  echo "WARNING: Parmana audit_db is false — Postgres not connected"
  exit 1
fi

echo "OK: Parmana healthy"
exit 0

Runtime manifest endpoint

For deeper version verification, use the runtime manifest:
curl http://localhost:3000/runtime/manifest
{
  "version": "1.0.0",
  "runtimeHash": "sha256:a3f8d2...",
  "capabilities": ["execute", "verify", "audit"],
  "supportedSchemaVersions": ["1.0.0"],
  "startedAt": "2024-01-15T10:00:00.000Z"
}
The runtimeHash in this response matches the runtimeHash embedded in every attestation produced by this runtime. Use it to confirm attestations were produced by the expected runtime version.

Troubleshooting

/health returns connection refused The server is not running or not bound to the expected port:
docker compose ps
docker compose logs server --tail=30
/health returns "status": "ok" but "audit_db": false Postgres is not connected. The server can still execute decisions, but audit records will not be stored:
docker compose logs postgres --tail=20
docker compose exec postgres pg_isready -U Parmana -d Parmana_audit
/health returns "verification": "error" The signing key or verifier is misconfigured. The server will respond to health checks but POST /execute will fail with 503. Check PARMANA_SIGNING_PROVIDER and the corresponding key path or value in .env. Health check passes but executions return 503 Check capabilities in the health response. If "execute" is not in the list, the execution runtime is not configured. This typically means the signing key loaded but the verifier did not.