Skip to content
z4j docs

What is z4j?

z4j is a control plane for Python task infrastructure. It gives Django, Flask, FastAPI, and bare-Python applications a modern dashboard for Celery, RQ, Dramatiq, Huey, arq, and taskiq - with persistent history, unified actions (retry / cancel / bulk-retry / restart), schedule CRUD, HMAC-chained audit logging, and secure-by-default redaction - without touching your existing task code.

It is not a new task queue

Section titled “It is not a new task queue”

z4j integrates with the queue you already run. If you're on Celery today, stay on Celery. Install the matching agent package, connect it to the brain, and verify the reported state in the dashboard.

It is not a pitch to replace Flower

Section titled “It is not a pitch to replace Flower”

Flower is a Celery viewer. z4j is a control plane:

  • Observation - task events, worker state, schedule runs, error rates.
  • Action - retry, cancel, bulk-retry, restart, purge - one vocabulary, offered per engine only where the adapter implements it. See the capability matrix.
  • Schedule CRUD - create/update/delete periodic tasks from the UI (on supported schedulers).
  • Persistent history - PostgreSQL-backed audit trail, survives broker restarts.
  • Multi-engine - run Celery + RQ in the same org without switching tools.

Mental model

Section titled “Mental model”

z4j is one process. Agents are how it sees the rest of your stack.

+------------------------------+
|             z4j              |   FastAPI + React dashboard
|  (Postgres persistence +     |   + WebSocket server for agents
|   unified action surface)    |   AGPL v3
+--------------^---------------+
               | WebSocket (outbound from your app)
               |
+--------------+---------------+
|        z4j-<framework>       |   thin pip package you install in
|   + z4j-<engine> adapters    |   your app (Django/Flask/FastAPI/bare)
|                              |   Apache 2.0
+------------------------------+
               |
               v
   Celery / RQ / Dramatiq / ...    your existing task code, unchanged

One sentence per feature

Section titled “One sentence per feature”
Feature What it does
Task list Every enqueue/start/success/retry/fail event across every engine, one timeline
Engine actions The dashboard exposes only the actions the connected engine adapter advertises; unsupported native operations stay hidden
Schedule CRUD Create, update, pause, delete periodic tasks (supported schedulers)
Audit log Every admin action and auth event, HMAC-chained and tamper-evident against anything writing through z4j. What that does and does not cover
RBAC Project-scoped roles (admin / operator / viewer) + multi-user invitations. There is no owner tier.
Rate limits Per-IP buckets on the login, password-reset, setup, invitation, MFA, agent-connect, and bulk-action routes. Not a fleet-wide ceiling: each worker process counts separately
Reconciliation Background worker reconciles "running forever" tasks against real engine state
Redaction Best-effort scrubbing of task fields in the worker and again at the brain, by key-name pattern and value shape. Not a guarantee, and schedule arguments are not redacted at all. What it covers

How do I install it?

Section titled “How do I install it?”

Three paths, three audiences. Pick the one that matches what you are doing:

If you are… Run
Evaluating (one-venv demo) pip install z4j - z4j + core in one command. AGPL-3.0.
Instrumenting a production app pip install z4j-<framework> z4j-<engine> - agents only, Apache 2.0.
Running z4j in production docker run z4jdev/z4j for the central process; agents via pip in the app.

See the install guide for the full breakdown of each path and their licence implications.

Section titled “What to read next”