Introduction
Durable Runner is an open-source, self-hosted background-job runner. You submit a versioned job — a name for the work plus a list of named steps — and it is acknowledged only after the record is durable on disk. A job the server said yes to survives the process dying: one framed append-only journal, written by a single writer under an exclusive lock, is the only authority. No database queue, no Redis.
Each step calls an HTTP handler you register and allowlist, and every attempt is at-least-once under one idempotency key — so a reply that vanished is reconciled, never repeated blindly. When a run finishes, its history expires on a schedule; the deduplication record stays so a resubmitted operation key returns the same run.
Who it is for
Section titled “Who it is for”- Developers submit, inspect, list and cancel runs with the
durableCLI or plaincurlagainst the HTTP API, and write step handlers in any language — a handler is just an endpoint that takes a POST and honours an idempotency key. - Operators run one Rust binary next to a filesystem: backups are consistent and verified, restores are checked before a byte is trusted, compaction keeps history bounded, and every queue, payload, retry and connection has a limit the server admits to instead of queueing silently.
How the pieces fit
Section titled “How the pieces fit”| Piece | What it is | Who uses it |
|---|---|---|
durable-server |
The coordinator: the HTTP API, the engine and the one journal writer | Your deploy |
| HTTP API | POST /jobs, GET /jobs/{id}, cancel, compact, backup, diagnostics |
The CLI, your scripts, the inspector |
durable CLI |
Submit, inspect, list, cancel, compact, backup and restore from a shell | Developers, operators |
| Step handlers | Your own HTTP endpoints, allowlisted at startup | The work itself |
| Inspector | A small read-mostly UI served by the server at /inspector/ |
Operators |
Start here
Section titled “Start here”Quick startBuild the server and CLI, run a job end to end, on this machine.
ConceptsThe journal, at-least-once and recovery — the model in one read.
JobsSubmit, inspect, schedule, cancel and page the run list over HTTP.
Self-hostingEvery flag, the deployment shape, backups, monitoring and security.
API referenceEvery route of the HTTP API, generated from the OpenAPI draft, with try-it.
ChangelogWhat changed and when, newest first.