Python arq Dashboard
Run arq 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 arq 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-arq3. 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 arq task history in Postgres or SQLite
- Adapter-advertised controls: submit_task, cancel_task (Job.abort)
- Scheduler integration via arq cron; 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-arq 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.
arq actions exposed
What the dashboard can actually do
Native actions
-
submit_task -
cancel_task (Job.abort)
Event capture
attach_to_worker_settings() chains onto on_job_start / on_job_end; it must be attached for lifecycle capture.
Reconciliation
arq.jobs.Job.status() + result_info(): clean deferred/queued/in_progress/complete mapping.
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 Dramatiq Dashboard
Middleware-driven Dramatiq observability.
Python Huey Dashboard
Lightweight Redis/SQLite queue, first-class.
Python taskiq Dashboard
Broker-agnostic async task framework.
arq on other frameworks
Same engine, different framework
Start using Python arq Dashboard
Self-hosted, open source, no SaaS, no telemetry. z4j runs anywhere Python or Docker runs.