Environment variables
All env vars are prefixed Z4J_ (brain-side) or read from the Z4J dict in framework settings (agent-side).
Brain environment variables
Section titled “Brain environment variables”| Variable | Required | Default | Description |
|---|---|---|---|
Z4J_DATABASE_URL | yes | - | PostgreSQL connection string (postgresql+asyncpg://...) |
Z4J_SECRET | yes | - | Main app secret (hex, 64 chars recommended) |
Z4J_SESSION_SECRET | yes | - | Session signing secret |
Z4J_AUDIT_SECRET | yes | - | HMAC audit chain secret |
Z4J_PUBLIC_URL | yes | - | Full public URL with scheme |
Z4J_DB_POOL_SIZE | no | 10 | asyncpg pool size |
Z4J_DB_POOL_MAX_OVERFLOW | no | 5 | Overflow connections |
Z4J_PASSWORD_MIN_LENGTH | no | 8 | Min password length |
Z4J_ARGON2_TIME_COST | no | 3 | argon2id time cost |
Z4J_ARGON2_MEMORY_COST | no | 65536 | argon2id memory (KiB) |
Z4J_ARGON2_PARALLELISM | no | 4 | argon2id threads |
Z4J_SMTP_HOST | no | - | SMTP server |
Z4J_SMTP_PORT | no | 587 | SMTP port |
Z4J_SMTP_USER | no | - | SMTP username |
Z4J_SMTP_PASSWORD | no | - | SMTP password |
Z4J_SMTP_FROM | no | - | From address |
Z4J_SMTP_TLS | no | starttls | TLS mode |
Z4J_SMTP_TIMEOUT | no | 10 | Timeout in seconds |
Z4J_RECONCILE_ENABLED | no | true | Enable reconciliation |
Z4J_RECONCILE_INTERVAL | no | 60 | Seconds between passes |
Z4J_RECONCILE_THRESHOLD_SECONDS | no | 1800 | ”Started” age before query |
Z4J_RECONCILE_MAX_PER_PASS | no | 500 | Max tasks per pass per agent |
Z4J_TASK_RETENTION_DAYS | no | 90 | Days before tasks are swept |
Z4J_METRICS_TOKEN | no | - | Token for /metrics endpoint |
Z4J_SENTRY_DSN | no | - | Sentry error reporting |
Z4J_AUDIT_VERIFY_INTERVAL | no | - | Seconds between auto-verify runs |
Z4J_BOOTSTRAP_ADMIN_EMAIL | no | - | Auto-provision admin on first boot |
Z4J_BOOTSTRAP_ADMIN_PASSWORD | no | - | Required with above |
Z4J_AUTOMIGRATE | no | true | Run Alembic on boot |
Agent-side settings
Section titled “Agent-side settings”Set in your framework’s config dict (e.g., Django settings.Z4J):
| Key | Required | Default | Description |
|---|---|---|---|
brain_url | yes | - | WebSocket URL of the brain |
token | yes | - | Agent bearer token |
project_id | no | "default" | Project ID |
agent_name | no | $HOSTNAME | Display name |
buffer_size | no | 1000 | Event buffer cap |
heartbeat_interval | no | 30 | Seconds between heartbeats |
reconnect_backoff_max | no | 60 | Max backoff on reconnect |
Precedence
Section titled “Precedence”Env vars override everything. File-based settings can supplement env vars but not replace them.