z4j

The all-in-one z4j umbrella package. Open-source control plane for Python task queues.

One pip install z4j brings z4j (dashboard + API) into your environment. Use extras to pull the agent packages your workers need: framework adapters (Django, Flask, FastAPI), engine adapters (Celery, RQ, Dramatiq, Huey, arq, TaskIQ), and their schedule companions. Every adapter cross-versions to the same z4j release line, so the floors stay in sync without manual pinning.

Compatibility

Brain: Python 3.11+, PostgreSQL 17+ (recommended) or bundled SQLite.

Every adapter pulled through the [django,celery] / [fastapi,arq] / etc. extras carries its own framework / engine version floor. Full per-adapter matrix at https://z4j.dev/reference/compatibility/.

What is z4j

z4j is one product split into 20 PyPI packages so each piece can be installed only where it's needed. The umbrella z4j is the operator-friendly entry point that wires the right combination together for you.

The architecture is straightforward:

• One brain process per environment. Dashboard, API, audit log. Persistent storage in SQLite or Postgres.
• One agent per worker / app process. A thin pip package that imports inside your Django / Flask / FastAPI app or your Celery / RQ / Dramatiq worker, opens an authenticated WebSocket to the brain, and streams every task / worker / queue / schedule event.
• Operator actions flow back the same channel. Retry, cancel, bulk retry, purge, restart, schedule CRUD, manual trigger.

z4j is AGPL v3 and isolated in its own process. The agent packages your application imports are Apache-2.0 each, so your application code is never AGPL-tainted.

What's in the box

• Brain (z4j). Server, dashboard, API, RBAC, HMAC-chained audit log, notifications, reconciliation worker.
• Engine-agnostic dynamic scheduler (z4j-scheduler). Optional companion process for projects that want one canonical scheduler across mixed engines, with live editing from the dashboard, HA leader election, and audited schedule mutations.
• Framework adapters. z4j-django, z4j-flask, z4j-fastapi, plus the framework-free z4j-bare for plain Celery / RQ / Dramatiq workers.
• Engine adapters. z4j-celery, z4j-rq, z4j-dramatiq, z4j-huey, z4j-arq, z4j-taskiq.
• Scheduler adapters. z4j-celerybeat, z4j-rqscheduler, z4j-apscheduler, z4j-arqcron, z4j-hueyperiodic, z4j-taskiqscheduler.

Try the live demo (no install)

demo.z4j.dev is the dashboard SPA running in your browser against pre-baked fake data. One click on the pre-filled login lands you in a populated control plane with four sample projects: Celery + celery-beat (small healthy starter), FastAPI + arq + arq-cron, Django + Celery + django-celery-beat with a current incident scenario (failing schedule, alert firing, worker offline), and a mixed-engine z4j-scheduler showcase driving Celery + RQ + Dramatiq workers from one place.

It is a navigable preview, not a sandbox: every Create / Update / Delete button toast-blocks (This is a demo. Refresh to reset; install z4j to make changes for real.), no real backend is connected, refresh resets to a clean state. Useful before you commit to pip install.

Install

The minimum useful install is z4j plus the framework + engine your stack actually uses. Use the extras instead of pinning each package by hand:

pip install z4j                          # brain only
pip install 'z4j[django,celery]'         # Django + Celery + celery-beat
pip install 'z4j[fastapi,arq]'           # FastAPI + arq + arq-cron
pip install 'z4j[flask,rq]'              # Flask + RQ + rq-scheduler

Each extra pulls the matching engine adapter and its schedule companion (e.g. [celery] pulls z4j-celery + z4j-celerybeat). The engine-agnostic dynamic scheduler is its own service and its own package, install it alongside the brain when you want it:

pip install z4j-scheduler

Then start z4j:

z4j serve

First boot mints HMAC secrets, runs Alembic migrations, creates a SQLite database at ~/.z4j/z4j.db, and prints a one-time setup URL to stderr that creates the first admin user. Set Z4J_DATABASE_URL=postgresql+asyncpg://... to use Postgres.

Why use z4j

z4j exists because every Python task queue ships its own viewer-grade tool (Flower for Celery, rq-dashboard for RQ, Dramatiq has none) and they all stop at viewer-grade. None of them give you:

• One dashboard across mixed engines (Celery + RQ + arq side by side, common operator workflow).
• An action surface (retry, cancel, bulk retry, purge, restart) that's safe to put in front of operations and compliance teams.
• A real audit log that an auditor can walk linearly.
• Live schedule editing across engines without per-daemon restarts.
• Self-hosted with no telemetry. z4j phones home only when an admin clicks Check for updates in Settings, and that URL is configurable.

z4j is the boring, self-hosted, audit-friendly choice. Built for homelab operators who want one place to look, and for compliance-sensitive teams who need to answer "who did what when" at quarter-end.

Documentation

Full docs at z4j.dev. The install guide at z4j.dev/getting-started/install/ covers all three paths (pip-SQLite, Docker-SQLite, Docker-Postgres).

License

AGPL-3.0-or-later, see LICENSE. Note: only z4j is AGPL. Every agent package your application imports is Apache-2.0, so your application code is never AGPL-tainted. Commercial licenses available; contact licensing@z4j.com.

Links

• Homepage: https://z4j.com
• Documentation: https://z4j.dev
• PyPI: https://pypi.org/project/z4j/
• Issues: https://github.com/z4jdev/z4j/issues
• Changelog: CHANGELOG.md
• Security: security@z4j.com (see SECURITY.md)