Skip to main content

Pure Python (pip)

Lightest

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

One pip install. No Docker. No container runtime.

Homelab Solo developer
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 (dashboard and backend bundled, SQLite by default)
pip install z4j-brain

# Boot with an admin account. Auto-runs migrations, generates secrets.
z4j-brain serve \
  --admin-email you@example.com \
  --admin-password change-me

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

Requirements

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

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

Scale envelope

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

Decision helper

Is this the right tier for you?

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

Not ideal when

  • Multiple concurrent admins (SQLite is single-writer)
  • High event throughput (>1k events/minute sustained)
  • Teams with heterogeneous hosts and OS versions
What ships

Capabilities in this tier

Upgrade path

How to move up a tier

Switch to z4j (Docker) or z4j + Postgres by graduating to the Docker compose presets. Your data, users, and schedules all migrate over.

Install adapters

Works with every engine and framework

Framework adapters

Django

Django

Django AppConfig integration, zero boilerplate.

Learn more
Flask

Flask

Flask extension pattern. One line to install.

Learn more
FastAPI

FastAPI

Lifespan-hook integration for async stacks.

Learn more

Engine adapters

Celery

Celery

The industry standard, covered end-to-end.

Learn more
RQ

RQ

Lightweight Redis queue, fully instrumented.

Learn more
Dramatiq

Dramatiq

Middleware-driven Dramatiq observability.

Learn more
Huey

Huey

Lightweight Redis/SQLite queue, first-class.

Learn more
arq

arq

Async Redis queue for FastAPI-era Python.

Learn more
taskiq

taskiq

Broker-agnostic async task framework.

Learn more
Other deployments

Compare with

z4j

Default

One container. Bundled SQLite. Zero required env vars.

z4j + Postgres

Production

Two services. Same image. Horizontal-scale ready.

Ready to run z4j with Pure Python (pip)?

Copy the install command above, run it, and open the dashboard on port 7700.

Full install guide Compare tiers