Quickstart - Django

This example assumes an existing Django 5 + Celery 5 application.

1. Install

pip install z4j-django z4j-celery z4j-celerybeat

2. Mint an agent token

From the brain dashboard → Agents → Mint token. Copy the token; it is shown once.

3. Configure settings

settings.py

INSTALLED_APPS += [
    "z4j_django",
]

Z4J = {
    "brain_url": env("Z4J_BRAIN_URL"),             # e.g. wss://z4j.internal.example.com/ws
    "token": env("Z4J_TOKEN"),                      # from step 2
    "project_id": env("Z4J_PROJECT_ID", default="default"),
    "agent_name": env("HOSTNAME", default="web"),
}

No changes to celery.py - the agent auto-detects Celery via Django app-config.

4. Restart

./manage.py runserver       # dev
# or
systemctl restart gunicorn  # prod

The agent opens a WebSocket on boot, advertises its engines in the hello frame, and starts streaming events. The dashboard populates within 2–5 seconds.

5. Verify

In the brain dashboard:

• Agents → your agent should show online with celery + celery-beat in adapters.
• Tasks → enqueue anything; it appears within ~100ms.
• Schedules → the full celery-beat schedule appears, read or read-write depending on your beat backend.

Multi-engine (optional)

If you also use RQ in the same Django project:

pip install z4j-rq z4j-rqscheduler

The agent will discover both engines automatically. No additional settings needed.

Troubleshooting

• Agent shows offline - check Z4J_BRAIN_URL uses wss:// in prod, ws:// in dev. Check firewall outbound to port 7700 (or your reverse-proxy port).
• Schedules read-only - you are using a read-only beat backend (e.g. django-celery-beat with DatabaseScheduler is writable; filesystem-based schedulers are not).
• No events - verify INSTALLED_APPS includes z4j_django after Celery’s apps, and that Celery is actually running.

See troubleshooting for more.