@dicabrio/durable

Durable execution engine CLI.

Local development

npx @dicabrio/durable
# equivalent: durable dev
# embedded PostgreSQL + API + scheduler + workers + dashboard on :3030

The first run downloads PostgreSQL into ~/.durable/pgdata. Dev workspaces are reset on each start, then Durable discovers DURABLE_DEV_APP_URL (default http://localhost:3000/api/durable), retrying until it is available. This mode is for local development, not production HA.

Production entrypoints

All production commands require an external DATABASE_URL:

durable migrate
durable serve
durable worker
durable scheduler

| Command | Responsibility | Health | |---|---|---| | serve | API, dashboard, realtime and Prometheus | /live, /ready, /metrics on PORT | | worker | callback execution and batch queue claims | /live, /ready, /metrics on DURABLE_HEALTH_PORT (3031) | | scheduler | timers, cron, retention and failure delivery | /live, /ready, /metrics on DURABLE_HEALTH_PORT (3032) | | migrate | advisory-locked migrations, then exit | process exit code |

Workers use PostgreSQL LISTEN/NOTIFY for low-latency wakeups with polling as the durable fallback. Unconstrained jobs use lock-free SKIP LOCKED batch claims; constrained jobs keep exact multi-rule gating. Short hot continuation chains reuse their queue row but acquire a fresh fenced lease for every callback. All long-running processes drain on SIGTERM.

| Variable | Default | Purpose | |---|---:|---| | PORT | 3030 | serve/dashboard port | | DURABLE_PG_PORT | 5434 | embedded dev PostgreSQL port | | DURABLE_PG_DIR | ~/.durable/pgdata | embedded dev data directory | | DURABLE_DEV_APP_URL | http://localhost:3000/api/durable | local endpoint to discover | | DURABLE_WORKERS | 4 worker / 2 dev | callback slots | | DURABLE_HEALTH_PORT | process-specific | worker/scheduler probes | | DURABLE_MAX_ATTEMPTS | 3 | total attempts when no function override exists | | DURABLE_CALLBACK_TIMEOUT_MS | 30000 | app callback timeout | | DURABLE_MANIFEST_TIMEOUT_MS | 10000 | pull-registration timeout | | DURABLE_MAX_BODY_BYTES | 1048576 | API and cumulative invocation limit | | DURABLE_MAX_RESPONSE_BYTES | 1048576 | callback/manifest response limit | | DURABLE_ADMIN_TOKEN | required in production | dashboard/admin authentication | | DURABLE_METRICS_TOKEN | unset | optional Bearer token for /metrics | | DURABLE_RETENTION_COMPLETED_DAYS | 0 | completed retention; zero disables automatic deletion | | DURABLE_RETENTION_FAILED_DAYS | 0 | failed retention; zero disables automatic deletion | | DURABLE_RETENTION_CANCELLED_DAYS | 0 | cancelled retention; zero disables automatic deletion |

Self-hosted operators remain responsible for PostgreSQL HA/PITR, backup restore drills, load balancing, scaling, secrets/TLS, monitoring and controlled upgrades. See the repository DEPLOY.md and ops/prometheus-alerts.yml.