Python Dramatiq Dashboard
Run Dramatiq as a plain Python worker process, no web framework, and you have working background jobs. Run it with z4j and you also have a dashboard, persistent history, the task controls this adapter can execute safely, scheduler integration, RBAC with invitations, and a tamper-evident audit log. z4j is one container or one Python process; the agent is two pip packages in the worker's venv and one install_agent() call at boot.
z4j-bare is the runtime every framework adapter is built on, used directly. It reads its credentials from the Z4J_* environment variables, opens one outbound WebSocket to z4j, keeps events in a local SQLite buffer while z4j is unreachable, and stops cleanly when you call runtime.stop(). Scripts, containers, systemd units and cron jobs all fit the same pattern, and one process can carry several engine adapters.
install
Install z4j alongside a plain Dramatiq worker
1. Install the brain
pip install z4j && z4j serveFirst boot prints a setup URL to stderr. Open it, create the first admin, and mint a token + HMAC secret for this agent.
2. Add the agent to the worker's venv
pip install z4j-bare z4j-dramatiq3. Start the agent at worker boot
# worker.py
from z4j_bare import install_agent
from z4j_celery import CeleryEngineAdapter
# brain_url / token / hmac_secret / project_id come from the matching
# Z4J_* environment variables; pass them explicitly to skip the lookup.
runtime = install_agent(
engines=[CeleryEngineAdapter(celery_app=my_celery_app)],
)
try:
run_your_worker() # sync or async; the runtime is independent
finally:
runtime.stop() # stop the transport, close the local bufferWhat you get
- Persistent Dramatiq task history in Postgres or SQLite
- Adapter-advertised controls: submit_task, retry_task (complete replacement inputs), purge_queue
- Scheduler integration via apscheduler; available controls depend on that scheduler adapter
- RBAC with invitations and password reset
- HMAC-chained tamper-evident audit log
- Notifications: email, Slack, Telegram, webhook
z4j-bare and z4j-dramatiq are Apache 2.0. Importing them into your worker process does not affect your application's licensing. z4j is AGPL-3.0-or-later, isolated in its own process.
Dramatiq actions exposed
What the dashboard can actually do
Native actions
-
submit_task -
retry_task (complete replacement inputs) -
purge_queue -
cancel_task (pending only; requires [abort] and real Abortable middleware) -
list_dead_letters (Redis lists the entries; RabbitMQ reports the count only)
Event capture
Z4JMiddleware, Dramatiq's blessed observability hook.
Reconciliation
Reports unknown; the brain's event-derived snapshot remains authoritative.
other Plain Python stacks
Plain Python with a different engine
Python Celery Dashboard
The industry standard, covered end-to-end.
Python RQ Dashboard
Lightweight Redis queue, fully instrumented.
Python Huey Dashboard
Lightweight Redis/SQLite queue, first-class.
Python arq Dashboard
Async Redis queue for FastAPI-era Python.
Python taskiq Dashboard
Broker-agnostic async task framework.
Dramatiq on other frameworks
Same engine, different framework
Start using Python Dramatiq Dashboard
Self-hosted, open source, no SaaS, no telemetry. z4j runs anywhere Python or Docker runs.