Hatchet: a Postgres-backed orchestration engine for background tasks and durable workflows

What Hatchet replaces in a background job stack

Most teams assemble a queue, a scheduler, a retry layer and a monitoring dashboard from separate pieces. Hatchet packages all four. The README describes it as "a platform for orchestrating background tasks, AI agents, and durable workflows at scale" with queuing, automatic retries, durability, real-time monitoring, alerting and logging in one system.

The intended user is a backend team that already writes application code in Python, TypeScript, Go or Ruby and does not want to operate a separate workflow service. Tasks are defined as ordinary functions in those languages. The README lists one-off background tasks with fire-and-forget or fire-and-wait semantics, configurable retry policies with optional exponential backoff, cron jobs and scheduled runs, and event or webhook triggers.

The distinguishing claim is the storage choice. The README states that Hatchet "uses Postgres as a durability layer for both the task runtime and the observability system, making it particularly easy to self-host." That is a real architectural commitment, not a marketing line: it means your task state and your run history live in the same database you probably already back up.

Durable tasks, DAGs and how work actually flows

Hatchet exposes two orchestration models, and the README links a guide on choosing between them. Durable tasks are fault-tolerant, long-running functions that can recover from failure. DAGs are directed acyclic graphs for data pipelines and simpler workflows.

Pausing is handled by durable primitives rather than by holding a process open. The README documents durable sleep, durable event waits, and combinations of the two. A workflow can therefore wait hours for an external event without a worker occupied for that time.

Distribution is the other half. Workers register and take work according to routing rules. The README describes task routing by worker labels for strict conditions and worker affinity for weighted scheduling. Worker slots cap how much work a single worker accepts. Concurrency policies enforce fair scheduling with limits keyed dynamically, and dynamic rate limits can enforce per-user caps against third-party APIs.

The repository layout confirms the split between server and clients: api/, cmd/, internal/, pkg/ and sql/ hold the Go service, while sdks/ holds the language SDKs and examples/ holds per-language samples. The dependency list includes pgx, pgxlisten, pgbouncer support and a NATS client, so Postgres is not the only moving part even though it is the durability layer.

Installing Hatchet locally with the CLI and Docker

The README gives one path for local setup and notes that it requires Docker installed locally. It works on macOS, Linux or WSL. The install script is fetched over curl and piped to bash, then the CLI reports its version, then the server starts.

curl -fsSL https://install.hatchet.run/install.sh | bash
hatchet --version
hatchet server start

After `hatchet server start`, the local platform should be running and reachable through its web UI. The README does not state the local UI port in the excerpt available here, so check the CLI output or the docs site for the address rather than guessing.

The README recommends signing up for Hatchet Cloud first even if you plan to self-host, so you can see what a fully deployed instance looks like. That is a reasonable suggestion for evaluating the UI before committing to an operation.

For a self-hosted deployment beyond a laptop, the repository ships docker-compose.yml, docker-compose.infra.yml and docker-compose.release.yml. The default compose file defines postgres on host port 5431, pgbouncer on 6431 and rabbitmq with its management UI on 15672. If you already run Postgres on your network, note that Hatchet's compose file brings its own instance with user, password and database all set to `hatchet`.

Where the Postgres-as-durability-layer design costs you

Putting task state and observability in the same Postgres instance is what makes self-hosting a compose file instead of a cluster. It is also the design's main risk. Every task transition becomes a database write, and the observability system shares that database. A high-throughput workload with verbose logging will contend with the scheduler on the same instance.

The compose file shows the maintainers are aware of this. Postgres is started with `max_connections=500` and `shared_preload_libraries=auto_explain`, plus a full set of auto_explain logging options that log analyze, buffers, WAL and triggers for statements over 1000 ms. A pgbouncer service runs in transaction pooling mode in front of it with `MAX_CLIENT_CONN=1000` and `DEFAULT_POOL_SIZE=50`. These are tuning knobs a plain queue would not need.

Two further limits are worth stating plainly. First, the SDK surface is Python, TypeScript, Go and Ruby. If your services are written in something else, Hatchet is the wrong tool unless you are willing to call the API directly. Second, the README does not document rollback or downgrade procedures for the server or for in-flight durable workflows. That silence matters if you run long-lived durable tasks and plan to upgrade frequently; verify the upgrade path against the docs before relying on it.

Hatchet compared with Celery and Temporal

Celery is the closest comparison for Python teams. Celery is a task queue with a broker (typically Redis or RabbitMQ) and a separate result backend; durability of a running task is not its core abstraction, and there is no built-in workflow UI in the box. Hatchet instead treats the database as the durability layer and ships the UI, alerting and metrics with the server. The practical difference shows up when a task must survive a process restart mid-execution: Hatchet's durable tasks are designed for that, while Celery's model expects you to build retry and recovery logic yourself.

Temporal is the closer comparison on semantics. Both offer durable execution with sleep and signal-style waits. The difference in approach is where state lives and what you operate. Hatchet's README positions Postgres as the single durability and observability store, which keeps the self-hosted footprint small. Temporal's architecture separates the workflow service from its persistence layer and is generally operated as a larger cluster. If you want durable execution with the smallest possible operational surface and you are comfortable with Postgres, Hatchet's trade-off is the more attractive one. If you need a runtime outside Hatchet's four SDKs, Temporal's language support is broader.

Licence, releases and the cost of staying current

Hatchet is MIT licensed, which is permissive and places few restrictions on commercial use or redistribution. The LICENSE file is at the repository root. This is not legal advice; if you redistribute Hatchet inside a product, read the licence text and your own obligations rather than relying on a summary.

Release cadence is visible in the repository. The three most recent releases are py/1.40.1 (Python SDK 1.40.1) on 2026-09-09, v0.106.5 (Hatchet 0.106.5) on 2026-09-08, and rb/0.8.0 (Ruby SDK 0.8.0) on 2026-09-07. The last push to the default branch was on 2026-09-10. The SDKs are versioned separately from the server, which means a Python SDK upgrade and a server upgrade are two different decisions.

That separation is the main upgrade cost. A server release and an SDK release can move independently, and the README does not document compatibility guarantees between a given server version and a given SDK version. The repository does include CHANGELOG.md and cliff.toml, so release notes are generated, but the practical step for anyone running this in production is to pin the server image and the SDK version together and read both changelogs before moving either.

Editorial conclusion

Adopt Hatchet if you already run Postgres, want a self-hosted queue with retries, cron, rate limits and a web UI in one deployment, and your team writes Python, TypeScript, Go or Ruby. Do not adopt it if you need a runtime outside those four SDKs, or if you want a queue that never touches your database. Before committing, verify three things: that your workload fits the worker model rather than a plain message broker, that your Postgres instance can carry the durability and observability write load, and that the licence terms of the release you install match your distribution plans.

Frequently asked questions

Official sources

1. hatchet-dev/hatchet on GitHub
2. License: MIT
3. Project website
4. README
5. Releases