Skip to content
z4j docs

Self-hosting

Sizing

Section titled “Sizing”
LoadBrainPostgres
< 10 agents, < 1M events/day1 CPU, 512 MiB, 10 GB disk1 CPU, 2 GiB, 10 GB
10-50 agents, < 10M events/day2 CPU, 2 GiB, 50 GB2 CPU, 4 GiB, 50 GB
50-200 agents, < 100M events/day4 CPU, 4 GiB, 200 GB4 CPU, 8 GiB, 500 GB

The brain is stateless beyond its Postgres connection. Horizontal scaling is supported in v1.1 (requires sticky routing for WebSockets).

Networking

Section titled “Networking”
  • Inbound to brain - TCP 7700 (HTTP + WebSocket) from the internet or private network.
  • Outbound from agent - agents initiate WebSocket connections to the brain. Agents need DNS + TCP 443 (if you TLS-terminate at a reverse proxy).
  • Brain to Postgres - usual asyncpg connection.

The brain does not need to reach agents. Agents sit behind NAT / private networks freely.

TLS

Section titled “TLS”

Terminate TLS at a reverse proxy (nginx / Caddy / Cloudflare). The brain speaks plain HTTP internally; X-Forwarded-Proto is respected.

Sample Caddy config:

z4j.example.com {
  reverse_proxy localhost:7700 {
    header_up X-Forwarded-Proto https
  }
}

Database

Section titled “Database”
  • Minimum: PostgreSQL 17. Recommended: PostgreSQL 18.3+.
  • Extensions: none required (no pgvector, no timescale in v1).
  • Connection pool: Z4J_DB_POOL_SIZE default 10, tune up for high-agent deployments.

Secrets

Section titled “Secrets”

For pip / SQLite installs the brain auto-mints secrets on first boot and persists them to ~/.z4j/secret.env. You don’t need to set anything; restarts pick up the same values from disk.

For Docker / Postgres production deployments, generate explicit secrets so they survive container replacement and live alongside your other infra config:

Terminal window
Z4J_SECRET=$(openssl rand -hex 32)
Z4J_SESSION_SECRET=$(openssl rand -hex 32)

Z4J_SECRET is the master from which the per-project HMAC signing secret is derived (deterministic - the brain re-derives it on every frame and never stores it). Z4J_SESSION_SECRET is independent and signs the user-session cookie.

Rotate by changing the env and restarting. Rotating Z4J_SESSION_SECRET invalidates all active user sessions (forces re-login). Rotating Z4J_SECRET breaks every existing agent’s HMAC and the audit chain - mint new agent tokens and run z4j audit verify to confirm chain integrity (see audit log).

Backups

Section titled “Backups”
  • Postgres: standard pg_dump or managed service snapshots. See backups guide.
  • Secrets: store in your secret manager (Vault, AWS Secrets Manager, SOPS).

Monitoring

Section titled “Monitoring”

The brain exposes /metrics in Prometheus format (auth-gated; set Z4J_METRICS_TOKEN). See operations § monitoring.