Plain Python

Name: z4j for Plain Python
Author: z4j

v1.12.0 Apache-2.0

z4j-bare

No web framework? One call at process boot.

The framework-free agent runtime every other adapter is built on, used directly. Standalone workers with no web framework (cron scripts, plain Celery, RQ or Dramatiq worker processes), frameworks z4j has no adapter for, and library code that ships its own agent all wire in the same way: install_agent() at boot returns a started runtime; hold the reference and stop it on shutdown.

Docs PyPI: z4j-bare Source

Latest: v1.12.0
Released: 2026-10-03
License: Apache-2.0

Install

bash

pip install z4j-bare

Pick an engine

Plain Python + any task engine

z4j-bare ships no engine extras. Install the engine adapter as its own package beside it, and the scheduler adapter when you want that engine's schedules on the dashboard.

Engine	Install command	Bundled scheduler
Celery recommended	`pip install z4j-bare z4j-celery`	`z4j-celerybeat` for celery-beat schedules
RQ	`pip install z4j-bare z4j-rq`	`z4j-rqscheduler` for rq-scheduler schedules
Dramatiq	`pip install z4j-bare z4j-dramatiq`	`z4j-apscheduler` for APScheduler schedules
Huey	`pip install z4j-bare z4j-huey`	`z4j-hueyperiodic` for huey-periodic schedules
arq	`pip install z4j-bare z4j-arq`	`z4j-arqcron` for arq-cron schedules
TaskIQ	`pip install z4j-bare z4j-taskiq`	`z4j-taskiqscheduler` for taskiq-scheduler schedules

pip install z4j-bare alone installs the runtime only. Add the engine adapter you run, and the scheduler adapter when you want its schedules on the dashboard.

Wire it in

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

Verify

Confirm the agent reaches the brain

Run the doctor as the same user the service runs under. It probes brain DNS / TCP / TLS / WebSocket upgrade, the on-disk buffer path, and reports auto-detected engines - exits 0 on all-green, 1 on any failure.

bash

python -m z4j_bare doctor

Catches the gunicorn-under-www-data silent startup failure (the agent now auto-relocates the buffer to $TMPDIR/z4j-{uid} when $HOME is unwritable), NAT / firewall / cert mismatches, and wrong-token / wrong-project_id problems with a specific failure reason. Add --no-websocket to skip the WS round-trip, --json for scripts. Reference.

What you get