Settings

The brain reads settings from env vars (primary) and an optional settings file. See env vars for the exhaustive env-var reference; this page groups settings by topic.

Database

Setting	Default	Notes
Z4J_DATABASE_URL	- (required)	postgresql+asyncpg://user:pw@host/db
Z4J_DB_POOL_SIZE	10	asyncpg pool size
Z4J_DB_POOL_MAX_OVERFLOW	5	max temporary connections above pool

Security

Setting	Default	Notes
Z4J_SECRET	- (required)	Main app secret. 64 hex chars recommended
Z4J_SESSION_SECRET	- (required)	Session signing key. Independent of Z4J_SECRET
Z4J_AUDIT_SECRET	- (required)	HMAC chain key
Z4J_PUBLIC_URL	- (required)	Full public URL (https://z4j.example.com). Validated: no whitespace, no userinfo, http(s) only

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

Setting	Default	Notes
Z4J_SMTP_HOST	-	hostname
Z4J_SMTP_PORT	587	STARTTLS default
Z4J_SMTP_USER	-	-
Z4J_SMTP_PASSWORD	-	-
Z4J_SMTP_FROM	-	From: header
Z4J_SMTP_TLS	starttls	starttls / ssl / none

Reconciliation

Setting	Default	Notes
Z4J_RECONCILE_ENABLED	true
Z4J_RECONCILE_INTERVAL	60	seconds
Z4J_RECONCILE_THRESHOLD_SECONDS	1800	30 min
Z4J_RECONCILE_MAX_PER_PASS	500	per agent

Retention

Setting	Default	Notes
Z4J_TASK_RETENTION_DAYS	90	daily sweep

Monitoring

Setting	Default	Notes
Z4J_METRICS_TOKEN	-	required to enable /metrics
Z4J_SENTRY_DSN	-	optional

First boot

Setting	Default	Notes
Z4J_BOOTSTRAP_ADMIN_EMAIL	-	skip setup URL; provision admin automatically
Z4J_BOOTSTRAP_ADMIN_PASSWORD	-	requires email above
Z4J_AUTOMIGRATE	true	run Alembic on boot