> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manthan.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# Health Checks

> Health endpoint reference, monitoring integration, and Kubernetes probes

## GET /health

Returns the runtime health status. No authentication required.

```bash theme={null}
curl http://localhost:3000/health
```

### Response schema

```json theme={null}
{
  "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"]
}
```

| Field                     | Type                | Description                                                                   |
| ------------------------- | ------------------- | ----------------------------------------------------------------------------- |
| `status`                  | `string`            | `"ok"` when the runtime is healthy                                            |
| `runtimeVersion`          | `string`            | Semver version of the running server                                          |
| `runtimeHash`             | `string`            | Content hash of the server binary — matches the `runtimeHash` in attestations |
| `verification`            | `string`            | `"ok"` when the signing key and verifier are configured correctly             |
| `audit_db`                | `boolean`           | `true` when Postgres is connected and schema is initialized                   |
| `signing_mode`            | `"env"` \| `"disk"` | How the signing key was loaded                                                |
| `capabilities`            | `string[]`          | Active capabilities — subset of `["execute", "verify", "audit"]`              |
| `supportedSchemaVersions` | `string[]`          | Policy schema versions this runtime accepts                                   |

### Interpreting the response

| Condition               | Meaning                                                                  |
| ----------------------- | ------------------------------------------------------------------------ |
| `status !== "ok"`       | Runtime is not healthy — do not send execution requests                  |
| `audit_db: false`       | Postgres is not connected — audit records will not be persisted          |
| `verification !== "ok"` | Signing or verification is misconfigured — executions will fail with 503 |
| Non-200 response        | Server is unreachable                                                    |

***

## Docker Compose health check

Add a Compose-level health check to the `server` service to enable dependent service health gating:

```yaml theme={null}
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

```yaml theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
#!/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:

```bash theme={null}
curl http://localhost:3000/runtime/manifest
```

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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.