Install z4j.

Three deployment paths, one platform. Whether you run a homelab Raspberry Pi or a production Kubernetes cluster, the z4j feature set ships in every tier.

Lightest

Pip (SQLite)

Pure Python. No container runtime required.

Best for

Solo developers, homelab, local dev, bare-metal servers, CI

Homelab Solo developer

Install Details

Default

Docker (SQLite)

One container. SQLite bundled in the image. No env vars required.

Best for

Homelab, small teams, evaluation, proof-of-concept

Homelab Small team Evaluation

Install Details

Production

Docker (Postgres)

Same image, external Postgres. Horizontal-scale ready.

Best for

Medium and larger businesses, regulated environments, compliance-sensitive teams

Small business Medium business Enterprise

Install Details

Side by side

Compare the three paths

Capability	Pip (SQLite)	Docker (SQLite)	Docker (Postgres)
Container runtime required	None (pure Python)	Docker	Docker + Postgres
Database	SQLite	SQLite (persisted volume)	PostgreSQL 17+
Services to run	1 process	1 container	2 containers
Agent count	~10	~50	1000+
Events per minute	~1k	~5k	300k+
Horizontal scaling
Full-text search
Range-partitioned events
Auto-migrations
Auto-generated secrets
Compliance-friendly (Postgres)

Lightest

Pip (SQLite)

Pure Python. No container runtime required.

Install command

bash

# Install the brain + umbrella (dashboard, backend, SQLite, all bundled)
pip install z4j

# Start it. First boot auto-mints HMAC secrets, runs migrations, and prints
# a one-time setup URL to stderr. Open the URL to create the first admin.
# z4j auto-detects the server's hostname, FQDN, and LAN IPs - so you can
# reach the dashboard via any of them out of the box.
z4j serve

# Then open http://<your-server>:7700 in your browser.

# Adding a public domain (e.g. tasks.example.com pointed via reverse proxy):
z4j allowed-hosts add tasks.example.com    # persisted to ~/.z4j/allowed-hosts
z4j allowed-hosts list                      # show what's whitelisted
z4j allowed-hosts remove old-host.example   # idempotent
# Restart z4j serve to pick up changes.

# Useful CLI commands (z4j and z4j-brain are aliases - same entry point):
z4j check               # config + DB + migrations at head
z4j status              # version, DB URL, user/project/agent counts
z4j createsuperuser     # provision an admin without the setup URL
z4j changepassword      # reset a user password
z4j migrate upgrade head    # run alembic migrations explicitly
z4j audit verify        # verify the HMAC-chained audit log
z4j reset-setup         # mint a fresh setup URL (e.g. expired token)

What runs

One Python process

z4j-brain serves the FastAPI API, the WebSocket agent gateway, and the React dashboard from a single process. SQLite lives on local disk.

Requirements

Python 3.11 or newer
No Docker, no Redis, no broker required
Writes to ~/.z4j/z4j.db (SQLite)

Use this when

Running z4j on a Raspberry Pi or homelab NUC
Evaluating z4j locally before committing to a container
CI jobs that need a task dashboard ephemerally
Air-gapped Python environments where Docker is not permitted

Database

SQLite (auto-created at ~/.z4j/z4j.db)

Scale envelope

Up to ~10 agents, ~1k events/minute, single-host deployment

Full details

Default

Docker (SQLite)

One container. SQLite bundled in the image. No env vars required.

Install command

bash

# The default. One file. SQLite bundled in the image.
git clone https://github.com/z4jdev/z4j.git && cd z4j
cp .env.example .env       # fill Z4J_SECRET + Z4J_SESSION_SECRET
docker compose up -d

# Tail logs for the first-boot admin setup URL.
docker compose logs -f z4j-brain

# Or skip interactive setup with bootstrap env vars in .env:
#   [email protected]
#   Z4J_BOOTSTRAP_ADMIN_PASSWORD=<long random>

# Add Caddy auto-HTTPS on top:
docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d

What runs

z4j-brain

z4jdev/z4j:latest

One image. Bundles the FastAPI backend, the React dashboard, and the SQLite driver. Auto-generates secrets on first boot, persists them to the z4j_data volume, auto-runs migrations. Exposes port 7700.

Requirements

Docker 20.10 or newer
Port 7700 bound to localhost by default (reverse-proxy for public access)
Persistent volume for SQLite database and persisted secrets

Use this when

First-time evaluation: clone the repo, docker compose up, done
Internal tools for a team of 2 to 20 developers
Homelab Docker Compose stacks (Synology, Unraid, TrueNAS)
Customer demos and sales engineering POCs
Single-instance production where ops simplicity wins over scale

Database

SQLite, stored in the z4j_data named volume

Scale envelope

Up to ~50 agents, ~5k events/minute, single container deployment

Full details

Production

Docker (Postgres)

Same image, external Postgres. Horizontal-scale ready.

Install command

bash

# Two services. Same z4jdev/z4j image as the default compose; it auto-
# switches to Postgres because Z4J_DATABASE_URL is set. No build required.

git clone https://github.com/z4jdev/z4j.git && cd z4j
cp .env.example .env

# Edit .env and fill in your secrets:
#   POSTGRES_PASSWORD=<long random>
#   Z4J_SECRET=$(openssl rand -hex 32)
#   Z4J_SESSION_SECRET=$(openssl rand -hex 32)
#   Z4J_PUBLIC_URL=https://z4j.yourdomain.com
#   Z4J_ALLOWED_HOSTS=z4j.yourdomain.com

docker compose -f docker-compose.postgres.yml up -d

# Capture the first-boot setup URL from the brain logs:
docker compose -f docker-compose.postgres.yml logs -f z4j-brain

# Or skip interactive setup entirely with bootstrap env vars in .env:
#   [email protected]
#   Z4J_BOOTSTRAP_ADMIN_PASSWORD=<long random>

# Layer Caddy auto-HTTPS on top:
docker compose -f docker-compose.postgres.yml -f docker-compose.caddy.yml up -d

What runs

z4j-brain

z4jdev/z4j:latest

Same image as the default. Bundles backend plus dashboard. Connects to external Postgres via Z4J_DATABASE_URL.

z4j-postgres

postgres:18-trixie

Your primary datastore. Holds events, tasks, schedules, users, HMAC-chained audit log, and partitioned event history.

Requirements

Docker Compose v2+ or Kubernetes
PostgreSQL 17 or newer (18+ recommended for 3x I/O improvements)
Reverse proxy with TLS (Caddy, nginx, Traefik) or cloud load balancer
Secrets management (env, Vault, Sealed Secrets, etc.)

Use this when

Self-hosted production deployments with audit requirements
Central Postgres with point-in-time recovery already in place
Teams with dedicated infrastructure or platform engineering
Compliance regimes (SOC 2, HIPAA, ISO 27001) that require Postgres
Kubernetes stacks with a Helm chart on the roadmap

Database

PostgreSQL 17+ (18.3+ recommended)

Scale envelope

1000+ agents, 5000+ events/second, multiple brain replicas behind a load balancer

Full details

HTTPS setup

Reverse proxy, your choice.

z4j does not bundle a reverse proxy. Pick the TLS pattern that matches your existing infra.

Caddy overlay

One extra compose file. Auto-HTTPS via Let's Encrypt. Two minutes.

Homelab default

Traefik labels

Already running Traefik? Add seven labels to the brain service.

Cloudflare Tunnel

Zero public ports. TLS terminates at Cloudflare's edge.

nginx + certbot

Classic, familiar, works everywhere. On-host or in-container.

Full TLS setup guide

Next step

Install the agent in your app

After the brain is running, drop the agent package into your Django, Flask, or FastAPI app. One pip install plus three environment variables.

Django

Django AppConfig integration, zero boilerplate.

pip install z4j-django[celery]

Learn more

Flask

Flask extension pattern. One line to install.

pip install z4j-flask[celery]

Learn more

FastAPI

Lifespan-hook integration for async stacks.

pip install z4j-fastapi[arq]

Learn more

Pick your engine

Every tier supports every engine

Install one or more engine adapters alongside your framework. Every deployment tier supports all six.

Celery

The industry standard, covered end-to-end.

Learn more

RQ

Lightweight Redis queue, fully instrumented.

Learn more

Dramatiq

Middleware-driven Dramatiq observability.

Learn more

Huey

Lightweight Redis/SQLite queue, first-class.

Learn more

arq

Async Redis queue for FastAPI-era Python.

Learn more

taskiq

Broker-agnostic async task framework.

Learn more

Architecture FAQ

One image, one clear story.

Answers to the common confusions about z4j's container layout.

Is the frontend a separate container?

No. The brain image bundles the FastAPI backend and the compiled React dashboard together. The backend serves the dashboard as static HTML, CSS, and JS from the same process. There is no second container for the UI.

Is there a separate image for each tier?

No. Both Docker tiers use the same z4jdev/z4j image. The runtime picks SQLite or Postgres based on the Z4J_DATABASE_URL environment variable.

Then what are the image tags for?

Tags pin versions, not modes. Use :latest for the most recent release (currently 1.0.5), or pin a specific version like :1.0.5 for reproducible deploys. Multi-arch: linux/amd64 + linux/arm64.

How many services for z4j + Postgres?

Two. z4j-brain runs the backend and dashboard from one image. z4j-postgres runs Postgres. No separate frontend.

Does the brain need Redis or RabbitMQ?

No. The brain communicates with your agents over a direct WebSocket. Your task queue engine uses whatever broker it already uses (Redis, RabbitMQ, SQS). The brain observes, it does not re-broker.

Can I migrate from SQLite to Postgres later?

Yes. Point Z4J_DATABASE_URL at your Postgres instance and restart. The same image reconnects, runs migrations, and picks up your users, audit chain, and schedules.

Still picking a tier?

Solo developer or homelab: start with pip. Team of 2-20: default z4j compose. Anyone with existing Postgres or compliance needs: z4j + Postgres.

Start with z4j (default) Full install docs