Pip (SQLite)

Lightest

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

Pure Python. No container runtime required.

Homelab Solo developer

Sources

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

PyPI GitHub

Architecture

What runs: 1 process

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

1

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.

Install

Get running in minutes

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)

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.