Install z4j

z4j has two moving parts — a brain (dashboard + API + Postgres) and agents (thin pip packages that run inside your app). Which install path is right for you depends on what you are doing.

Pick your path

You are…	What you run	What you pip install	Licence you end up with
Evaluating — want to try z4j on a laptop in 2 minutes	Brain + agents in one venv	pip install z4j	AGPL-3.0 (umbrella pulls in the brain)
Instrumenting a production app — already have Django / Flask / FastAPI / a bare worker and want to add observability	Agents only (brain runs separately on another host / container)	pip install z4j-<framework> z4j-<engine> z4j-<scheduler>	Apache 2.0 (agents only)
Operating the brain in production	Brain via Docker + agents via pip in your app	docker run z4jdev/z4j for the brain; pip install z4j-<framework> z4j-<engine> in the app	Brain AGPL-3.0 (isolated on its own host), agents Apache 2.0

If you are unsure, start with the evaluator path, then migrate to the production path once you know z4j is a fit. You never need to change your application code when switching paths — the agent packages are the same.

Path 1 — Evaluator (one pip)

# Brain + core + SQLite, all in one venv:
pip install z4j

# Start the brain:
z4j-brain serve --port 7700 --admin-email you@dev.local --admin-password changeme

# Open http://localhost:7700

Add a stack with extras:

pip install "z4j[django,celery]"       # Django + Celery + beat
pip install "z4j[fastapi,arq]"         # FastAPI + arq + cron
pip install "z4j[flask,rq,rqscheduler]"
pip install "z4j[all]"                  # every engine, every framework

The extras install the agents on top of the brain into the same venv. That is the evaluator-friendly shape — brain and agents coexist, you poke the dashboard immediately.

Caution

pip install z4j installs the brain server, which is AGPL-3.0. If you cannot accept AGPL anywhere in your environment (even a dev venv), skip to Path 2.

Path 2 — Instrumenter (per-adapter pip, Apache-only)

Install only the agent packages you need — nothing pulls in the AGPL brain:

pip install z4j-django z4j-celery z4j-celerybeat       # Django + Celery + beat
pip install z4j-fastapi z4j-arq z4j-arqcron             # FastAPI + arq + cron
pip install z4j-flask z4j-rq z4j-rqscheduler            # Flask + RQ + scheduler
pip install z4j-bare z4j-dramatiq z4j-apscheduler       # bare Python + Dramatiq + APScheduler

Every agent package is Apache 2.0. Nothing you import into your app has any copyleft obligation. The brain runs somewhere else (Docker container, separate host) and your agents connect to it over a WebSocket.

Framework	Engines	Schedulers
z4j-django	z4j-celery, z4j-rq, z4j-dramatiq, z4j-huey, z4j-arq, z4j-taskiq	z4j-celerybeat, z4j-rqscheduler, z4j-apscheduler, z4j-hueyperiodic, z4j-arqcron, z4j-taskiqscheduler
z4j-flask	same	same
z4j-fastapi	same	same
z4j-bare	same	same

Every agent transitively installs z4j-core — you never need to name it explicitly.

Path 3 — Production (Docker brain + pip agents)

Run the brain with Docker

docker run -d --name z4j-brain \
  -p 8080:7700 \
  -e Z4J_DATABASE_URL=postgresql+asyncpg://z4j:password@db/z4j \
  -e Z4J_SECRET=$(openssl rand -hex 32) \
  -e Z4J_SESSION_SECRET=$(openssl rand -hex 32) \
  -e Z4J_PUBLIC_URL=https://z4j.internal.example.com \
  z4jdev/z4j:latest

On first boot the brain prints a setup URL to stderr. Visit it to create your admin account.

Docker Compose

See the Docker guide for a full docker-compose.yml including Postgres and reverse proxy.

Kubernetes

See the Kubernetes guide. A Helm chart is on the v1.1 roadmap.

Install agents in your app

Use the Path 2 pip install z4j-<framework> z4j-<engine> shape — not the umbrella. Your production application venv stays Apache-2.0-only and never has the brain code locally.

Why the split matters

• Brain (AGPL-3.0) runs as infrastructure. Most organisations deploy it on an isolated host (or a Docker container on a shared host). Nothing in your application code links against it — agents talk to the brain over the network.
• Agents (Apache 2.0) live inside your application process. They need to be freely usable in any context — proprietary code, closed-source deployment, etc. Apache 2.0 is the lowest-friction permissive license with a patent grant.
• Umbrella z4j (AGPL-3.0) is a convenience installer for the all-in-one case. Declaring it AGPL is honest — pip install z4j puts AGPL code (the brain) onto your disk, so the umbrella itself carries that licence.

See License for the full split rationale.

Configure

Once the brain is running and agents are installed, wire them up with the framework-specific quickstart:

• Django
• Flask
• FastAPI
• Bare Python

Minimum requirements

Component	Minimum
Brain	Python 3.13+ (container ships 3.14), PostgreSQL 17+ (18.3 recommended), 512 MiB RAM
Agent	Python 3.13+ (matches brain), 20 MiB overhead
Network	Agent → Brain WebSocket (outbound from agent; brain does not need to reach the agent)

Version compatibility

z4j v1.0.x ships with a unified 1.0.0 version across every package (brain, core, bare, every adapter). Agents from v1.0.x talk to v1.0.x brains on wire-protocol v2.

Cross-version mismatches surface as a dashboard banner (“agent version mismatch”). Feature parity is not guaranteed across major versions. See versioning.