Configuration

Complete environment variable reference for z3rno-server, organized by feature. Every flag below maps to a pydantic-settings field in z3rno_server.config.

Configuration reference

Every Z3rno surface beyond the always-on base (store / recall / forget / audit / sessions / api-keys / conversations / limits / graph) is opt-in via a gating flag. Default values produce a working local-dev stack against docker-compose.dev.yml; flip the gates as you light up Forge / Ingest / Refine / forget-proof / OpenTelemetry / etc.

Source of truth: z3rno-server/src/z3rno_server/config.py. Variables names are case-insensitive; values are read from environment or .env file. As of v0.20.0.

Database

Variable	Default	Notes
DATABASE_URL	postgresql+asyncpg://z3rno:z3rno_dev_password@localhost:5432/z3rno	Async driver required (asyncpg).
DATABASE_POOL_SIZE	20	SQLAlchemy connection pool.
DATABASE_MAX_OVERFLOW	10	Pool overflow above DATABASE_POOL_SIZE.
DATABASE_READ_URL	""	Opt-in (Phase G slice 1). When set, pure-read GET endpoints route SELECTs to the replica. WAL replay lag is checked at session acquire; over-threshold falls back to primary.
READ_REPLICA_LAG_CHECK_ENABLED	true	Honoured only when DATABASE_READ_URL is set.
READ_REPLICA_LAG_THRESHOLD_SECONDS	5.0	Replica skipped when lag exceeds this.

Valkey / Redis

Variable	Default	Notes
VALKEY_URL	""	Preferred. Falls back to REDIS_URL when empty.
REDIS_URL	redis://localhost:6379/0	Back-compat alias.

Embedding

Variable	Default	Notes
EMBEDDING_PROVIDER	litellm	Routes embedding calls through LiteLLM.
EMBEDDING_MODEL	text-embedding-3-small	OpenAI default. Output dim is hard-coded at 1536 (ADR-001).
OPENAI_API_KEY	""	Required for OpenAI embeddings. Also the fallback for LLM_API_KEY and MULTIMODAL_API_KEY.

Authentication

Variable	Default	Notes
Z3RNO_API_KEY	""	Dev bypass. When set, this key authenticates without a DB lookup. The fresh-local-server default is z3rno_sk_test_localdev — rotate it for any non-localhost deploy. Production keys are generated via POST /v1/api-keys.
Z3RNO_DEV_ORG_ID	""	Org id stamped on requests authenticated by Z3RNO_API_KEY.
API_KEY_HEADER	X-API-Key	Alternative to Authorization: Bearer.
API_KEY_CACHE_TTL	60	Valkey cache TTL (seconds) for verified API keys.
JWT_SECRET_KEY	""	HMAC secret for dashboard JWT auth. Required when JWT auth is in use.
JWT_ALGORITHM	HS256
JWT_EXPIRY_MINUTES	60

Rate limiting

Variable	Default	Notes
RATE_LIMIT_ENABLED	true	Toggles the entire middleware.
RATE_LIMIT_PER_MINUTE	60	Per-API-key request budget.
RATE_LIMIT_BURST	10	Burst allowance above the steady rate.

Server / CORS / logging

Variable	Default	Notes
SERVER_HOST	0.0.0.0
SERVER_PORT	8000
DEBUG	false
CORS_ORIGINS	http://localhost:3000,http://localhost:8000	Comma-separated.
LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR / CRITICAL.
LOG_FORMAT	json	json or text.

Celery backpressure

Variable	Default	Notes
CELERY_QUEUE_DEPTH_THRESHOLD	1000	When broker depth exceeds this, /v1/ingest* returns 503 with Retry-After. Set to 0 to disable.
CELERY_QUEUE_DEPTH_RETRY_AFTER_SECONDS	30	Value of the Retry-After header on backpressure 503s.

---

Phase A — Forge (DISTILL_ENABLED)

The Forge pipeline is dormant unless DISTILL_ENABLED=true. With the flag off, /v1/distill is not registered and z3rno.forge_distill self-rejects.

Variable	Default	Notes
DISTILL_ENABLED	false	Master gate.
LLM_PROVIDER	openai	openai / anthropic / gemini / bedrock / ollama.
LLM_MODEL	openai/gpt-4o-mini	LiteLLM-namespaced model id.
LLM_API_KEY	""	Falls back to OPENAI_API_KEY when provider is openai.
LLM_TIMEOUT_SECONDS	30.0	Per-call timeout.
LLM_MAX_RETRIES	3	Tenacity retry budget.
STRUCTURED_OUTPUT_FRAMEWORK	instructor	Only instructor is shipped.
DISTILL_CHUNK_SIZE	1024	tokens
DISTILL_CHUNK_OVERLAP	128	tokens
DISTILL_MAX_CONCURRENCY	4	Per-job LLM fan-out semaphore.
DISTILL_SUMMARY_STYLE	concise	concise / bullet / abstractive.
DISTILL_PROVENANCE_REQUIRED	false	Phase F slice 1. When true, aborts the Forge transaction if any Memo’s provenance + audit chain entry can’t be written.

Phase B.1 — Ingestion (INGEST_ENABLED)

/v1/ingest, /v1/ingest/file, /v1/datasets and the z3rno.ingest_run worker register only when INGEST_ENABLED=true.

Variable	Default	Notes
INGEST_ENABLED	false	Master gate.
STORAGE_BACKEND	local	local (filesystem) or s3 (Phase B.2).
STORAGE_LOCAL_DIR	/var/lib/z3rno/artifacts
INGEST_MAX_FILE_BYTES	52428800 (50 MB)	Hard cap on uploads + URL responses.
INGEST_MAX_CSV_ROWS	10000
INGEST_DEFAULT_CHUNK_SIZE	1024	Per-request override allowed.
INGEST_AUTO_DISTILL	true	Chain ingest → z3rno.forge_distill when DISTILL_ENABLED=true.
URL_FETCH_TIMEOUT_SECONDS	15.0
URL_ALLOWED_SCHEMES	http,https

Phase B.2 — Multimodal / S3 / Tavily / Playwright

Each capability flips on independently — multimodal doesn’t require S3, Tavily doesn’t require multimodal, etc.

Multimodal (image + audio)

Variable	Default	Notes
MULTIMODAL_ENABLED	false	Registers image/audio loaders with the registry on worker startup.
MULTIMODAL_PROVIDER	litellm	litellm (OpenAI vision + Whisper) / local (CLIP + openai-whisper, requires z3rno-core[multimodal-local]) / stub.
MULTIMODAL_VISION_MODEL	openai/gpt-4o-mini
MULTIMODAL_AUDIO_MODEL	whisper-1
MULTIMODAL_API_KEY	""	Falls back to OPENAI_API_KEY.
MULTIMODAL_MAX_AUDIO_BYTES	26214400 (25 MB)	OpenAI Whisper cap.
MULTIMODAL_MAX_IMAGE_BYTES	20971520 (20 MB)

S3 storage backend (STORAGE_BACKEND=s3)

Variable	Default	Notes
S3_BUCKET	""	Required when STORAGE_BACKEND=s3.
S3_REGION	us-east-1
S3_ENDPOINT_URL	""	Empty for AWS; set for MinIO / Cloudflare R2 / DigitalOcean Spaces.
S3_PREFIX	z3rno	Bucket-key prefix sandbox.
S3_ACCESS_KEY_ID	""	Empty → default AWS credential chain (IRSA / IAM role).
S3_SECRET_ACCESS_KEY	""

Tavily web search (registers /v1/ingest/search)

Variable	Default	Notes
TAVILY_API_KEY	""	Set to register the search route.
TAVILY_SEARCH_DEPTH	basic	basic / advanced.
TAVILY_MAX_RESULTS	5

URL loader Playwright fallback

Variable	Default	Notes
URL_PLAYWRIGHT_ENABLED	false	Requires pip install 'z3rno-core[playwright]'.
URL_PLAYWRIGHT_MIN_CHARS	200	Below this, fall back to Playwright.
URL_PLAYWRIGHT_TIMEOUT_SECONDS	30.0

Phase C — Retrieval

Variable	Default	Notes
ALLOW_CYPHER_QUERY	false	Gates strategy="CYPHER" on recall. Off by default — the strategy exists but is hidden behind 403 until an operator opts in.

Phase D — Refine / Ontology / Codegraph (REFINE_ENABLED)

/v1/feedback, /v1/refine, and the z3rno.refine_run worker register only when REFINE_ENABLED=true.

Refine

Variable	Default	Notes
REFINE_ENABLED	false	Master gate.
REFINE_SCHEDULE	cron:0 */6 * * *	Per-cron-tab format; consumed by the legacy schedule wiring. Multi-tenant scheduler uses REFINE_BEAT_INTERVAL_SECONDS below.
FEEDBACK_WEIGHT_DECAY	0.95	EMA blend factor per refine cycle.
REFINE_MAX_PER_TICK	10	v0.19.4. Tenants picked per scheduler tick.
REFINE_BEAT_INTERVAL_SECONDS	0	v0.19.4. Set > 0 to enable multi-tenant beat scheduler. 0 keeps the scheduler dormant (on-demand only).
REFINE_INFER_ENABLED	false	LLM stage: propose edges for under-connected Memos.
REFINE_SUMMARIZE_ENABLED	false	LLM stage: per-cluster SUMMARY Memos.
REFINE_INFER_MAX_CANDIDATES	50	Per-cycle LLM call cap.

Ontology grounding (Forge integration)

Variable	Default	Notes
ONTOLOGY_RESOLVER	none	none or rdflib. Set rdflib to resolve distilled entities to OWL URIs.
ONTOLOGY_FILE_PATH	""	Required when ONTOLOGY_RESOLVER=rdflib. Path to OWL/TTL/RDF file.
ONTOLOGY_MATCHING_STRATEGY	fuzzy	exact or fuzzy.
ONTOLOGY_FUZZY_THRESHOLD	0.80	Minimum score for fuzzy match (0-1).

Codegraph (Ingest integration)

Variable	Default	Notes
CODEGRAPH_ENABLED	false	When true, ingest of code sources also runs the tree-sitter extractor. Requires pip install 'z3rno-core[codegraph]'.
CODEGRAPH_LANGUAGES	python,typescript	Allow-list. v0.19.5 added go and rust.

Phase F — Differentiation

Memory-tier routing

Variable	Default	Notes
MEMORY_TIER_AUTO_ROUTE	false	When true, the AUTO strategy asks the MemoryTierRouter for tiers and fans out across them. Per-request tier_route in the recall body always wins.

Compliance-graded retrieval (PII redaction)

Variable	Default	Notes
RETRIEVAL_REDACTION_ENABLED	false	Role-aware regex scrubbing on recall results.
RETRIEVAL_REDACTION_RULES_PATH	""	YAML rules file. Empty → built-in defaults (email / SSN / credit card / US phone).

Forget-with-proof

Variable	Default	Notes
FORGET_PROOF_ENABLED	false	When true, every forget() emits a Merkle-rooted, ed25519-signed certificate; GET /v1/forget/{cert_id} is registered.
FORGET_PROOF_SIGNING_KEY_PATH	""	PEM-encoded unencrypted Ed25519 private key.
FORGET_PROOF_SIGNER_KEY_ID	default	Rotation-friendly label stamped on each cert.

Distributed worker backends

Variable	Default	Notes
DISTRIBUTED_BACKEND	celery	celery / modal / k8s_jobs. Off-default backends lazy-import — missing SDK raises JobBackendError, not a crash.
MODAL_APP_NAME	z3rno
K8S_JOBS_NAMESPACE	z3rno
K8S_JOBS_IMAGE	""	Image used when DISTRIBUTED_BACKEND=k8s_jobs.

Phase G — Agent-native

Usage telemetry + budgets

Zero = no cap (default). Non-zero values trip BudgetExceededError on Forge / refine pre-flight; the job is rejected before any LLM/embedding work.

Variable	Default
USAGE_BUDGET_DAILY_TOKENS	0
USAGE_BUDGET_DAILY_LLM_CALLS	0
USAGE_BUDGET_DAILY_EMBEDDINGS	0
USAGE_BUDGET_MONTHLY_TOKENS	0
USAGE_BUDGET_MONTHLY_LLM_CALLS	0
USAGE_BUDGET_MONTHLY_EMBEDDINGS	0

Per-tenant overrides land via PUT /v1/tenants/me/budgets (v0.20.3). See Components → z3rno-server for the endpoint.

Cross-tenant admin (v0.22.1, managed-hosting)

Variable	Default	Notes
SUPERADMIN_ENABLED	false	Gates /v1/tenants/{org_id}/budgets. Both this and SUPERADMIN_API_KEY must be set for the routes to register.
SUPERADMIN_API_KEY	""	Deploy-time secret. The bearer presented on a request is matched against this directly — there is no DB lookup. Treat like a root password; rotate by config push.

The cross-tenant surface is off by default and stays invisible (not in the OpenAPI spec) until both vars are set. See the Managed-hosting guide for the ops playbook.

Recall counter batching (v0.22.0)

Variable	Default	Notes
RECALL_COUNT_BATCH_ENABLED	false	Coalesce recall_count bumps into one UPDATE per org per window. Per-process.
RECALL_COUNT_BATCH_WINDOW_MS	50	Flush cadence. Smaller = fresher counters + more writes; larger = staler counters + better coalescing.

Off by default; flip on once your deployment’s benchmark numbers ratify the win. The single-process laptop bench delta is +2-4% ops/sec at high concurrency with a -19 to -25% p99 reduction at 20-30 concurrent recalls.

OpenTelemetry tracing

Variable	Default	Notes
OTEL_ENABLED	false	When true, instruments FastAPI; W3C traceparent propagates outbound.
OTEL_SERVICE_NAME	z3rno-server
OTEL_ENVIRONMENT	production	Stamped as deployment.environment on every span.
OTEL_EXPORTER_OTLP_ENDPOINT	""	OTLP/gRPC endpoint.

v0.20 — Operator polish

NOTIFY/LISTEN audit drain (v0.20.2)

Variable	Default	Notes
Z3RNO_AUDIT_LISTEN_ENABLED	false	Gate read by the z3rno-audit-listener console-script (the singleton pod deployed by the chart’s auditListener.enabled block). When true, the listener opens LISTEN z3rno_audit_pending and fires z3rno.audit_drain on every notification (~50 ms wake instead of waiting for beat).

Audit-drain tunables (read by the engine; surface them through chart beat.audit.*)

Variable	Default	Notes
AUDIT_DRAIN_BATCH_SIZE	500	Rows per drain transaction.
AUDIT_DRAIN_INTERVAL_SECONDS	1.0	Beat tick interval. Recommended 60.0 when listener is enabled (poll becomes fallback).
AUDIT_DRAIN_MAX_ORGS_PER_TICK	100	Bounds per-tick fan-out.

---

Reference

• Source: z3rno-server/src/z3rno_server/config.py
• Helm surface: Components → z3rno-helm — these env vars all surface as values keys.
• Server reference: Components → z3rno-server — endpoint × gating-flag matrix.
• Per-release detail: changelogs/