Configuration

zaanix.config.yaml, environment overrides and every setting that matters — security, database, auth, DuckDB, MCP, lakehouse, the AI model, cache and observability.

How configuration is resolved#

zaanix.config.yaml is loaded from $ZAANIX_CONFIG, ./zaanix.config.yaml, or /etc/zaanix/zaanix.config.yaml. Values may reference environment variables with ${VAR} / ${VAR:-default} (nesting allowed). Later sources win:

1. Built-in defaults
2. The YAML file
3. Well-known short names (PORT, JWT_SECRET, ENCRYPTION_KEY, ZAANIX_DATA_DIR, DATABASE_URL, OIDC_*, DUCKDB_MEMORY_LIMIT, …)
4. Generic overrides ZAANIX__<SECTION>__<KEY> — for example ZAANIX__DUCKDB__MAX_RESULT_ROWS=1000

The final object is validated with zod; the process refuses to start on invalid configuration. The effective, redacted config is available with zaanix config and GET /api/admin/config.

security#

database#

metadata_url — sqlite://zaanix_meta.db (default) or postgres://user:pass@host:5432/db; run_migrations (default true) applies migrations at start.

auth#

duckdb#

mcp#

default_page_size / max_page_size (50 / 200 rows per tool call), max_cell_chars (truncation), require_confirmation_for_mutations (the HITL gate, default on), sse_heartbeat_seconds.

lakehouse#

enabled, statement_timeout_seconds (Databricks warehouse statements, default 120), max_rows (rows returned to the grid from a warehouse), materialize_max_rows (rows pulled into a DuckDB table).

copilot#

provider (anthropic | openai | gemini | deepseek | openrouter | kimi | groq | mistral | xai | ollama | custom | bedrock | bedrock_agent | agentcore | none) — the deployment-time default; a model saved from Settings › AI › Model by an administrator takes precedence — model, api_key, base_url (Ollama / OpenAI-compatible), aws_region, bedrock_agent_id, bedrock_agent_alias_id, agentcore_runtime_arn, allow_byok (users may bring their own key), max_context_tables, include_summaries, max_output_tokens, temperature.

cache#

See Result cache for how keys are built.

mosaic#

See Interactive exploration & Mosaic dashboards.

apps#

Streamlit data apps run by ZAANIX (see Data apps).

observability#

metrics_enabled, metrics_require_auth (Prometheus at /metrics), otel.enabled, otel.service_name, otel.exporter_otlp_endpoint, otel.console_exporter.

Example#

server:
  port: ${PORT:-4200}
  public_url: "${ZAANIX_PUBLIC_URL:-}"
security:
  jwt_secret: "${JWT_SECRET}"
  encryption_key: "${ENCRYPTION_KEY}"
  data_jail_directory: "${ZAANIX_DATA_DIR:-./data}"
  filesystem_mode: "${ZAANIX_FILESYSTEM_MODE:-full}"
database:
  metadata_url: "${DATABASE_URL:-sqlite://zaanix_meta.db}"
auth:
  strategy: "${AUTH_STRATEGY:-local}"
  oidc:
    groups_claim: "${OIDC_GROUPS_CLAIM:-groups}"
    admin_groups: []
    sync_groups: true
duckdb:
  default_memory_limit: "${DUCKDB_MEMORY_LIMIT:-80%}"
  query_timeout_seconds: ${DUCKDB_QUERY_TIMEOUT_SECONDS:-60}
cache:
  max_bytes: ${ZAANIX_CACHE_MAX_BYTES:-268435456}