Framework - Django

Package: z4j-django - requires Django 4.2+.

Install

pip install z4j-django

Add to INSTALLED_APPS after Celery-related apps:

INSTALLED_APPS = [
    ...,
    "django_celery_beat",   # if applicable
    "z4j_django",
]

Settings

All settings live under the Z4J dict:

Z4J = {
    "brain_url": "wss://z4j.example.com/ws",   # required
    "token":     "z4j_agent_...",              # required (use env var)
    "project_id": "default",                   # optional
    "agent_name": "web-01",                    # optional (default: hostname)
    "buffer_size": 1000,                       # optional
    "heartbeat_interval": 30,                  # optional (seconds)
    "reconnect_backoff_max": 60,               # optional (seconds)
}

Required

Key	Meaning
brain_url	WebSocket URL of the brain (wss:// in prod, ws:// in dev)
token	Agent bearer token (from Dashboard → Agents → Mint token)

Optional

Key	Default	Meaning
project_id	"default"	Project to register under
agent_name	$HOSTNAME	Display name in the agent list
buffer_size	1000	Events buffered during network partition
heartbeat_interval	30	Seconds between heartbeats
reconnect_backoff_max	60	Max seconds between reconnect attempts

Lifecycle

• AppConfig.ready() kicks off agent start in a background asyncio task.
• SIGTERM / SIGINT trigger graceful shutdown via Django’s signal hooks.
• In tests, agent start is auto-disabled when settings.TESTING=True.

Management-command-safe

Management commands (./manage.py migrate, custom commands) don’t start the agent unless explicitly requested. Add --with-z4j if you want agent lifecycle in a long-running management command.

Multi-process / Gunicorn

Each gunicorn worker is a separate agent. This is by design - you can see per-worker load in the dashboard. Names default to {HOSTNAME}-{PID}.

To coalesce at the display level, set agent_name to the same value across workers - but you’ll lose per-process visibility.

Channels / ASGI

z4j-django auto-detects ASGI (Daphne / Uvicorn / Hypercorn) and integrates with the existing event loop - no extra configuration.

Troubleshooting

• Agent never connects - check DJANGO_SETTINGS_MODULE is set, INSTALLED_APPS includes z4j_django, and check startup logs for the [z4j] agent starting line.
• Schedule CRUD disabled - requires django-celery-beat with DatabaseScheduler. Filesystem schedulers are read-only.

See engines for engine-specific notes.