z4j

Default

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

One container. Bundled SQLite. Zero required env vars.

Homelab Small team Evaluation

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. docker compose up.
# No secrets to set, no Postgres, no broker. It just works.
docker compose up -d

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

# Or skip the interactive setup with env vars in .env:
#   Z4J_BOOTSTRAP_ADMIN_EMAIL=you@example.com
#   Z4J_BOOTSTRAP_ADMIN_PASSWORD=change-me

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

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