Configuration

chukei reads a single YAML file. Values support ${VAR} env interpolation (unset vars are a startup error), and any field can be overridden with CHUKEI_* env vars (CHUKEI_LISTEN_BIND, CHUKEI_PLUGINS_CACHE_ENABLED, …).

listen:
  bind: "0.0.0.0:8443"
  tls:                          # required for real drivers
    cert: "/etc/chukei/tls.crt"
    key:  "/etc/chukei/tls.key"

upstream:
  snowflake:
    account: "abc12345.eu-west-2.aws"   # locator incl. region; no credentials here, ever

storage:
  backend: filesystem           # s3 | azure | gcs | filesystem
  path: "/var/lib/chukei"

coalesce:                       # identical concurrent reads share one execution
  enabled: true
  scope: session                # RLS-safe; `account` is opt-in

savings:
  enabled: true
  db_path: "/var/lib/chukei/savings.db"
  usd_per_credit: 3.0
  conservative_factor: 0.7      # deliberate under-claiming
  default_warehouse_size: M
  warehouse_sizes: { BI_WH: M, TRANSFORM_WH: L }

plugins:
  cache:
    enabled: true
    default_ttl_secs: 900
    table_ttls: { "ANALYTICS.MARTS.*": 86400 }
    determinism_gate: strict
    blame_sample_rate: 0.05     # fraction of hits double-checked upstream
    max_entries: 10000
    # persist_path: "/var/lib/chukei/cache"   # dir 0700, entries 0600
  router:  { enabled: false }
  rewrite: { enabled: true, rules: [all] }
  suspend:
    enabled: true
    mode: suggest-only          # suggest-only | enforce
    role: CHUKEI_SUSPENDER
    sweep_interval_secs: 30
    # Model gates (defaults are production-conservative):
    min_observations: 20        # arrivals seen before the model speaks
    horizon_secs: 60            # "would a query arrive within this window?"
    p_threshold: 0.2            # suspend when P(arrival in horizon) < this
    cooldown_secs: 300          # per-warehouse gap between suspend actions
    # Metadata statements (SHOW/DESCRIBE/USE) and cache hits never count
    # as warehouse activity — cached dashboards let their warehouse sleep.
  attribute:
    enabled: true
    auto_query_tag: true
    dbt_metadata_parser: true
    sources: [hint_comment, application_name, dbt_meta]

# Only needed for suspend.mode: enforce
# service_account:
#   user: "${CHUKEI_SVC_USER}"
#   password: "${CHUKEI_SVC_PASSWORD}"
#   role: CHUKEI_SUSPENDER

observability:
  prometheus: { enabled: true, port: 9090 }   # /metrics + /healthz

evidence:
  enabled: true
  signing:
    enabled: false
    # private_key_path: "/etc/chukei/signing.key"   # chukei evidence keygen
  retention_days: 2555

Validate any file with chukei validate config --file chukei.yaml.