Skip to main content
Plain Python + Celery . Self-hosted . Open source

Python Celery Dashboard

Run Celery 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 z4j Plain Python integration details Celery adapter details

install

Install z4j alongside a plain Celery worker

1. Install the brain

bash 
pip install z4j && z4j serve

First 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

bash 
pip install z4j-bare z4j-celery

3. Start the agent at worker boot

python 
# 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 buffer

What you get

  • Persistent Celery task history in Postgres or SQLite
  • Adapter-advertised controls: submit_task, retry_task, cancel_task, bulk_retry, purge_queue, restart_worker, pool_grow / pool_shrink, add_consumer / cancel_consumer, rate_limit
  • Scheduler integration via celery beat; available controls depend on that scheduler adapter
  • RBAC with invitations and password reset
  • HMAC-chained tamper-evident audit log
  • Notifications: email, Slack, Telegram, webhook
License

z4j-bare and z4j-celery 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.

Celery actions exposed

What the dashboard can actually do

Native actions

  • submit_task
  • retry_task
  • cancel_task
  • bulk_retry
  • purge_queue
  • restart_worker
  • pool_grow / pool_shrink
  • add_consumer / cancel_consumer
  • rate_limit

Event capture

Signals (in-process) + broker-events monitoring (fanout). Auto-switches based on worker pool type.

Reconciliation

celery.result.AsyncResult, authoritative; covers every backend (redis, rpc, db, etc.).

other Plain Python stacks

Plain Python with a different engine

Plain Python +

Python RQ Dashboard

Lightweight Redis queue, fully instrumented.
Plain Python +

Python Dramatiq Dashboard

Middleware-driven Dramatiq observability.
Plain Python +

Python Huey Dashboard

Lightweight Redis/SQLite queue, first-class.
Plain Python +

Python arq Dashboard

Async Redis queue for FastAPI-era Python.
Plain Python +

Python taskiq Dashboard

Broker-agnostic async task framework.

Celery on other frameworks

Same engine, different framework

+ Celery

Django Celery Dashboard

Django AppConfig integration, zero boilerplate.
+ Celery

Flask Celery Dashboard

Flask extension pattern. One line to install.
+ Celery

FastAPI Celery Dashboard

Lifespan-hook integration for async stacks.

Start using Python Celery Dashboard

Self-hosted, open source, no SaaS, no telemetry. z4j runs anywhere Python or Docker runs.

Install z4j Read the docs