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.
| 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.
| 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.
| 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 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.
| 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). |
| 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. |
| 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.
| 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. |
