z4j 1.0.1

z4j - open-source control plane for Python task infrastructure

z4j

Open-source control plane for Python task infrastructure. License: AGPL v3 - commercial license available (contact [e-mail]). Status: v1.0.1 (production-ready).

A modern, self-hosted alternative to Flower / Prometheus-only task monitoring. Monitor, manage, and control Celery / RQ / Dramatiq / Huey / arq / TaskIQ / APScheduler workers, tasks, schedules, and queues from a single dashboard.

This is the umbrella package. Installing z4j gets you the flagship experience (brain + dashboard + SQLite) plus a clean way to layer in adapter engines via extras.

Quick start

pip install z4j

# Generate the two required HMAC signing secrets
export Z4J_SECRET=$(python -c "import secrets; print(secrets.token_urlsafe(48))")
export Z4J_SESSION_SECRET=$(python -c "import secrets; print(secrets.token_urlsafe(48))")

z4j-brain migrate upgrade head
z4j-brain serve

On first run, z4j-brain serve prints a one-time setup URL (http://localhost:7700/setup?token=...). Open it in your browser to create the admin account, then you land on the dashboard at http://localhost:7700/.

See z4j-brain for the complete configuration reference (defaults, retention, rate limits, Argon2 cost, etc.).

Install shapes

# Just the brain (dashboard + SQLite)
pip install z4j

# Brain + Celery adapter (pulls z4j-celery + z4j-celerybeat)
pip install "z4j[celery]"

# Brain + Django + Celery
pip install "z4j[django,celery]"

# Switch the brain to PostgreSQL
pip install "z4j[postgres]"

# Every adapter engine at once (useful for CI)
pip install "z4j[agents]"

# The kitchen sink
pip install "z4j[all]"

Which adapter extras exist

Extra	Installs	For
[celery]	z4j-celery + z4j-celerybeat	Celery workers + beat scheduler
[django]	z4j-django	Django task telemetry
[flask]	z4j-flask	Flask background tasks
[fastapi]	z4j-fastapi	FastAPI BackgroundTasks
[rq]	z4j-rq + z4j-rqscheduler	RQ workers + rq-scheduler
[dramatiq]	z4j-dramatiq	Dramatiq actors
[huey]	z4j-huey + z4j-hueyperiodic	Huey + periodic tasks
[arq]	z4j-arq + z4j-arqcron	arq workers + cron
[taskiq]	z4j-taskiq + z4j-taskiqscheduler	TaskIQ + scheduler
[apscheduler]	z4j-apscheduler	APScheduler jobs
[bare]	z4j-bare	Bare (no engine) agents

Which umbrella extras exist

Extra	Installs	For
[postgres]	z4j-brain[postgres] (asyncpg)	Production PostgreSQL backend
[agents]	every engine adapter	Full-stack dev / CI testing
[all]	[agents,postgres]	Kitchen sink

Agent-only installs (no AGPL in your app's venv)

If you're adding z4j to an existing Django / Celery / Flask application and you need Apache-2.0-only dependencies (no AGPL in your proprietary code's venv), skip the umbrella and install the standalone adapter packages directly:

pip install z4j-core z4j-django    # SDK + Django adapter
pip install z4j-celery             # SDK + Celery adapter
pip install z4j-rq                 # SDK + RQ adapter

Every adapter package is Apache 2.0 and depends only on z4j-core (also Apache 2.0). Point Z4J_BRAIN_URL at a running brain and the adapter will start streaming telemetry.

Licensing

z4j (this umbrella package) is AGPL v3 because it installs z4j-brain by default. If that is incompatible with your policy, use the agent-only install recipe above.

• Agent packages (z4j-core, z4j-celery, z4j-django, ...): Apache 2.0. Free for proprietary use.
• Brain server (z4j-brain): AGPL v3. Commercial license available - contact [e-mail].

The split is deliberate. The brain is the network service operators run; the agents are the client libraries integrators embed. AGPL protects the server; Apache makes integration frictionless.

Documentation

Complete documentation, tutorials, API reference, deployment guides: https://z4j.dev.

• Source: https://github.com/z4jdev/z4j
• Issues: https://github.com/z4jdev/z4j/issues
• Changelog: https://github.com/z4jdev/z4j/blob/main/CHANGELOG.md