Skip to content
z4j docs

Settings

z4j reads settings from env vars (primary). See env vars for the exhaustive reference; this page groups the operator-facing settings by topic for skimming.

Database

Section titled “Database”
Setting Default Notes
Z4J_DATABASE_URL - (required) postgresql+asyncpg://user:pw@host/db
Z4J_DATABASE_STATEMENT_CACHE_SIZE 50 Per-connection asyncpg prepared-statement cache cap. 0 disables.
Z4J_DATABASE_MAX_INACTIVE_CONNECTION_LIFETIME_SECONDS 60 SQLAlchemy pool_recycle. Shorter values rotate per-connection caches faster under sustained load.
Z4J_AUTO_MIGRATE true Run Alembic head migrations on brain boot. Set false for orchestrators that handle migrations separately.

The connection pool itself (pool_size=20, max_overflow=10) is currently fixed at engine creation time and not exposed as a setting.

Security

Section titled “Security”
Setting Default Notes
Z4J_SECRET - (required) Master HMAC signing key. Drives the frame HMAC, the audit-log row HMAC, and session-secret derivations. 64 hex chars recommended.
Z4J_SESSION_SECRET - (required) Session-cookie signing key. Independent of Z4J_SECRET.
Z4J_PUBLIC_URL - (required) Full public URL (https://z4j.example.com). Validated: no whitespace, no userinfo, http(s) only.
Z4J_PREVIOUS_SECRETS - Comma-separated previous master secrets still accepted during rotation. Writes use the new Z4J_SECRET.
Z4J_PREVIOUS_SESSION_SECRETS - Comma-separated previous session secrets still accepted during cookie-rotation.

The audit-log HMAC chain uses Z4J_SECRET itself; there is no separate audit secret.

Auth / passwords

Section titled “Auth / passwords”
Setting Default Notes
Z4J_PASSWORD_MIN_LENGTH 8 Minimum 8.
Z4J_ARGON2_TIME_COST 3 OWASP 2024 minimum.
Z4J_ARGON2_MEMORY_COST 65536 64 MiB, in KiB.
Z4J_ARGON2_PARALLELISM 4 Threads.

SMTP

Section titled “SMTP”

SMTP servers are not configured via env vars. Each notification channel record carries its own smtp_host, smtp_port, smtp_user, smtp_password, smtp_from, and smtp_tls fields. See notifications and smtp-presets.

Reconciliation

Section titled “Reconciliation”
Setting Default Notes
Z4J_RECONCILIATION_SWEEP_SECONDS 300 Seconds between reconciliation passes (default 5 min).
Z4J_RECONCILIATION_STALE_THRESHOLD_SECONDS 900 Minimum age in started state before a task is eligible for reconciliation (default 15 min).

Retention

Section titled “Retention”
Setting Default Notes
Z4J_EVENT_RETENTION_DAYS 30 Days raw events rows live before the partition is dropped.
Z4J_AUDIT_RETENTION_DAYS 90 Days audit_log rows live before the retention worker prunes them.

Monitoring

Section titled “Monitoring”
Setting Default Notes
Z4J_METRICS_AUTH_TOKEN - (auto-minted) Bearer for /metrics. Auto-minted into ~/.z4j/secret.env if absent and Z4J_METRICS_PUBLIC is unset. z4j metrics-token prints; z4j metrics-token rotate rotates.
Z4J_METRICS_PUBLIC false 1 leaves /metrics open. Use only with a firewalled or proxy-authenticated endpoint.

z4j does not bundle a Sentry SDK. Application logs go to stdout as JSON; ship them with Fluent Bit / Vector / Loki / Datadog.

First boot

Section titled “First boot”
Setting Default Notes
Z4J_BOOTSTRAP_ADMIN_EMAIL - Skip the setup URL and provision an admin automatically.
Z4J_BOOTSTRAP_ADMIN_PASSWORD - Required with the email above. Eagerly popped from os.environ after use.