Docker (SQLite)

Default

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

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

Homelab Small team Evaluation

Sources

Current release: v1.6.5 (released 2026-05-27)

Docker Hub GitHub PyPI

Image: z4jdev/z4j:1.6.5 (pin version) or z4jdev/z4j:latest (track current)

Multi-arch: linux/amd64, linux/arm64. The SAME image handles SQLite and Postgres - the database is selected at runtime via Z4J_DATABASE_URL.

Architecture

What runs: 1 process

z4j ships one image for the brain. Backend and dashboard are bundled. There is no separate frontend container.

1

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.

Install

Get running in minutes

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

After the brain is running, open http://localhost:7700 and sign in.

Verify

Confirm everything is wired up

Each framework adapter ships a `doctor` command that probes brain reachability, TLS, WebSocket upgrade, and the on-disk buffer path. Run it as the same user the service runs under.

Django

bash

python manage.py z4j_doctor

Flask

bash

python -m z4j_flask doctor

FastAPI

bash

python -m z4j_fastapi doctor

Bare / Celery / RQ / etc.

bash

python -m z4j_bare doctor

Exits 0 on all-green, 1 on any failure. Add --no-websocket to skip the WS round-trip, --json for scripts. Catches the common www-data-can't-write-$HOME startup failure (the agent now auto-relocates the buffer to $TMPDIR/z4j-{uid} and logs a single WARNING). See service-user deployments.

Hostname / domain access

Reach the brain via any name you want

The brain validates the HTTP `Host:` header on every request to defend against cache-poisoning. Auto-detect handles the common cases; the `z4j allowed-hosts` CLI handles the rest.

What's auto-allowed (no config)

localhost, 127.0.0.1, [::1]
The system hostname + FQDN (incl. Tailscale's <host>.<tailnet>.ts.net)
Every LAN IP bound on the host (covers 192.168.x.x, Docker bridges, Tailscale)

Adding a custom domain (one-time, persisted)

For a public DNS name (reverse proxy, Cloudflare Tunnel, internal LB), persist it once via the CLI:

bash

z4j allowed-hosts add tasks.example.com
z4j allowed-hosts list                  # show current set
z4j allowed-hosts remove old.example     # idempotent
z4j allowed-hosts path                   # ~/.z4j/allowed-hosts
# Restart `z4j serve` to pick up the change.

Precedence (highest first)

Z4J_ALLOWED_HOSTS env - pins the list, replaces auto-detect
--allowed-host CLI flag - additive, repeatable
~/.z4j/allowed-hosts file - persistent, additive
Auto-detect - localhost + hostname + FQDN + LAN IPs

Security

Rejected requests get a generic 400 in production mode (no internal hostname leakage). Dev mode shows a verbose response with the rejected host and a fix command. Operators always get the verbose detail in the server log via request_id correlation.

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

Database

SQLite, stored in the z4j_data named volume

Scale envelope

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

Decision helper

Is this the right tier for you?

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

Not ideal when

You already run Postgres and want central backups
You need brain-side horizontal scaling
Dozens of simultaneous admins issuing bulk actions

What ships

Capabilities in this tier

All 6 engines supported
All 3 framework adapters
Full dashboard UI
RBAC and audit log
HMAC wire protocol
Auto-migrations on boot
Auto-generated + persisted secrets
Horizontal brain replicas

HTTPS

Put a TLS terminator in front

The brain image binds HTTP on port 7700. In production, route traffic through a reverse proxy that terminates TLS. z4j does not bundle one because your infrastructure likely already has one.

For a homelab with a public DNS name, the optional Caddy compose overlay shipped in the repo gives you auto-HTTPS via Let's Encrypt in about two minutes. Teams with existing Traefik, Cloudflare, or nginx plug z4j in with a few lines of config.

TLS setup guide

Upgrade path

How to move up a tier

Switch to docker-compose.postgres.yml when you outgrow SQLite. The same image binary auto-detects Postgres from Z4J_DATABASE_URL. Your settings, projects, and audit chain transfer.

Install adapters