Runtime, services and sleep

Let a web app sleep

A single HTTP service sleeps after five idle minutes by default. Its next request wakes it. Hub preserves memory and disk; the first request may take longer while it resumes. Browsers can show a waking screen.

Inspect without waking it:

hub app my-app runtime

Static sites serve published files and do not need sleep or RAM suspension.

Keep background work running

Workers and multi-service apps default to always on. Use always-on mode for queues, scheduled jobs, or work that must continue without web requests:

hub app my-app runtime --always-on

Sleep pauses every service in the instance, including background jobs. Enable it only when all services can safely pause between requests. Start a sleeping instance before changing its policy.

Pause an eligible app

hub app my-app suspend

Suspension saves memory and allows a later request to wake the app. It waits for completion by default, including CLI JSON and MCP. To return an operation ID immediately, use hub app my-app suspend --no-wait, or pass wait: false to hub_app_suspend.

Sleep-policy changes still return an operation ID. Poll that ID, or one returned by a lifecycle command with --no-wait:

hub app my-app runtime --operation ID

Wait for succeeded. Inspect failed, expired, or unknown results before retrying; none confirms success.

Use MCP

hub_app_runtime is read-only and requires hub:read. It accepts target and an optional operation ID. Inspect without waking the app:

{ "target": "my-app" }

Change policy with hub_app_runtime_set, which requires hub:write. Start a sleeping instance first. Choose exactly one setting: alwaysOn: true for background work, or sleepAfter: 300 for five idle minutes when every service can safely pause.

{ "target": "my-app", "alwaysOn": true }

The change affects every service in the instance. Poll hub_app_runtime with the returned operation ID; replace the example UUID below:

{ "target": "my-app", "operation": "123e4567-e89b-42d3-a456-426614174000" }

Wait for succeeded, as with CLI operations. Explicit Compose x-hub-runtime settings override policy on redeploy, so preserve them. CLI flags remain --sleep-after, --always-on, and --operation on hub app my-app runtime.

Shared services

A shared dependency may serve several apps. Hub checks registered dependencies before sleeping an instance, so an active consumer can keep it awake. External connections are not automatically discovered.

Customer runtime actions affect the whole instance. Dependency wiring and worker moves are administrator operations.

Write apps that resume safely

Network connections and external transactions can time out during sleep. Reconnect after resume, keep durable job state in persistent storage, and use bounded retries for API calls. Make retried writes idempotent.

Stopping is different from suspension: it keeps the app offline. Restarting or redeploying does not preserve process memory.

Runtime options · Resource limits