@skilder-ai/runtime 0.9.25 → 0.10.1

package/README.md

@@ -38,14 +38,22 @@ This will start a long-living node process with the ability to host MCP Servers
 
 ## Running in Docker / Health check
 
-### Health endpoint
+### Health endpoints
 
-When `REMOTE_PORT` is set, the runtime exposes `GET /health`:
+When `REMOTE_PORT` is set, the runtime exposes two endpoints answering deliberately different questions.
+
+**`GET /health` — liveness.** Is the process up and serving? Always **`200 { status: 'ok' }`**, with no I/O. It is available as soon as the port binds, before the runtime has connected to NATS, and it stays up across reconnect cycles. **This is the one to point a `HEALTHCHECK` at.**
+
+**`GET /ready` — readiness.** Is this runtime connected, authenticated, and able to reach NATS?
 
 - **`200 { status: 'ok' }`** — NATS connected, an active round-trip probe (`flush`, 2s timeout) succeeded, and the runtime is authenticated
 - **`503 { status: 'error', message: '...' }`** — NATS disconnected, NATS unreachable (flush timed out), not authenticated, or an unexpected error occurred
 
-Health is independent of the remote MCP endpoints: a runtime that serves no MCP endpoint (no `MCP_REMOTE_ENABLED`) is still healthcheckable. The container image defaults `REMOTE_PORT` to `3001`, so every runtime container has a working healthcheck out of the box.
+Readiness only means something for a runtime that talks to a backend. A pure MCP server (`MCP_REMOTE_ENABLED` with no key — `STANDALONE_MCP_STREAM`) never connects or authenticates, so its `/ready` stays `503`: gate that one on `/health`, which is true as soon as it is serving.
+
+> **Never point a `HEALTHCHECK` at `/ready`.** Readiness depends on a remote service, so gating liveness on it means one backend blip restarts your whole fleet — and restarting cannot fix a backend that is down. Use `/ready` to gate traffic, or to alert on a runtime that has been unready for longer than your longest planned outage.
+
+Both endpoints are independent of the remote MCP endpoints: a runtime that serves no MCP endpoint (no `MCP_REMOTE_ENABLED`) is still healthcheckable. The container image defaults `REMOTE_PORT` to `3001`, so every runtime container has a working healthcheck out of the box.
 
 > **Note:** `npx`-installed runtimes bind no port unless you set `REMOTE_PORT` yourself, and stdio mode (`USER_KEY`) never starts an HTTP server — it is spawned per client, so a shared port would collide.
 
@@ -56,17 +64,18 @@ services:
   runtime:
     image: your-runtime-image
     environment:
-      REMOTE_PORT: "3001"          # web service (health); the image defaults this
+      REMOTE_PORT: "3001"          # web service (health/ready); the image defaults this
       MCP_REMOTE_ENABLED: "true"   # also serve the remote MCP endpoints on it
       RUNTIME_KEY: "<RUNTIME_API_KEY>"
       NATS_SERVERS: "nats:4222"
     healthcheck:
+      # Liveness, never readiness — see the note above.
       test: ["CMD", "curl", "-f", "http://localhost:3001/health"]
       interval: 10s
       timeout: 5s
       retries: 5
-      start_period: 60s  # Allow time for NATS connect + auth
+      start_period: 30s  # Only has to cover process startup, not the handshake
     restart: unless-stopped
 ```
 
-> **`start_period`**: Set this to at least 60s to allow enough time for the initial NATS connection and authentication handshake before Docker starts counting health check failures.
+> **`start_period`**: `/health` answers as soon as the process binds its port, so this only needs to cover startup — it does not have to wait out the NATS connection and authentication handshake.