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 is configurable through Z4J_DATABASE_POOL_SIZE (default 20) and Z4J_DATABASE_MAX_OVERFLOW (default 10). On PostgreSQL the brain refuses to start when the total is below what its enabled leader-gated workers need, because a pool that cannot seat them deadlocks rather than degrades. See environment variables.

Security

Section titled “Security”
Setting Default Notes
Z4J_SECRET - (required) Master HMAC signing key. Derives the per-project frame HMAC key, hashes agent tokens, and encrypts stored TOTP secrets. It does not sign sessions (that is Z4J_SESSION_SECRET below) and does not sign the audit log (that is Z4J_AUDIT_CHAIN_SECRET). 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 when verifying agent bearer tokens and stored secrets. Writes use the new Z4J_SECRET. It does NOT cover frame signing, so rotation still requires re-credentialing every agent. See incident response.
Z4J_PREVIOUS_SESSION_SECRETS - Comma-separated previous session secrets still accepted during cookie-rotation.
Z4J_AUDIT_CHAIN_SECRET - (required outside development) Dedicated audit-chain signing key, at least 32 bytes. Independent of Z4J_SECRET, with no fallback: the brain refuses to start without it outside development.
Z4J_AUDIT_CHAIN_PREVIOUS_SECRETS - Comma-separated previous audit-chain keys still accepted by the verifier during rotation. Writes use the current Z4J_AUDIT_CHAIN_SECRET.

The audit-log HMAC chain is signed with Z4J_AUDIT_CHAIN_SECRET, deliberately separate from Z4J_SECRET. See HMAC audit chain for why the separation matters and how activation works on an existing deployment.

Auth / passwords

Section titled “Auth / passwords”
Setting Default Notes
Z4J_PASSWORD_MIN_LENGTH 12 Default 12; configurable down to the supported floor of 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.
Z4J_AUDIT_CHAIN_VERIFY_ENABLED false Run the scheduled audit-chain verification worker. Off by default: verification walks every retained row, so an operator who has not asked for it does not pay for it. Leader-gated.
Z4J_AUDIT_CHAIN_VERIFY_INTERVAL_SECONDS 86400 Cadence for the scheduled verification. Floor 900 (15 minutes), ceiling 604800 (one week).

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.