Configuration

Two surfaces: leoflow.yaml (per-DAG, authoring) and server environment (LEOFLOW_*, the control plane). The canonical leoflow.yaml schema is docs/api/leoflow-yaml-schema.json.

leoflow.yaml

See DAG authoring for the override layers.

Python version support

Every value the schema accepts has a published, multi-arch, cosign-signed base image at ghcr.io/neochaotic/leoflow-runtime:py<version>. Nothing else does — if a version is not in the table above, no base image exists for it and the build fails on the pull.

Published until is the last date on which a release publishes that leg; a release cut after it ships no py<line> image. A — means the line is supported with no removal date set. The Status and Published-until cells are generated from nothing — they are written by hand — but scripts/check-python-runtime-matrix.sh reconciles them against the x-leoflow-python-deprecations block in the authoring schema, so a deprecation that moves in the schema and not here fails the build rather than leaving this table quietly telling you the opposite.

3.13 is the current ceiling, and it is set by the dbt adapters rather than by Airflow: dbt-core and dbt-postgres publish for 3.14, but dbt-snowflake, dbt-bigquery, dbt-databricks and dbt-duckdb stop at 3.13. A py3.14 base would give you an image where dbt-postgres installs and dbt-snowflake does not — discovered inside your build, not ours — so it is not published.

3.10 is deprecated. Python 3.10 reaches upstream end-of-life on 2026-10-31, and docker-library/python stops rebuilding an EOL line the day after (python:3.9-slim was last rebuilt 2025-11-01, one day after 3.9 went EOL). From that point python:3.10-slim — and so leoflow-runtime:py3.10 — receives no further OS security updates and accumulates unfixed CVEs indefinitely. The py3.10 leg keeps being published until 2026-10-31, so nothing breaks today; leoflow validate, leoflow compile and leoflow deploy warn when your project resolves to it.

There are two ways to resolve to it, and they have different fixes:

• You set python_version: "3.10". Set python_version: "3.11" (or later) and rebuild.
• You pinned base_image to a published py3.10 tag (…:py3.10, …:py3.10-v0.4.5). Repoint base_image to the matching py3.11 tag and rebuild. Changing python_version here does nothing: when base_image is set it is used verbatim and python_version is not consulted for the FROM.

Existing images keep running either way; the rebuild is what moves you.

This matters more than for most images because it is inherited: a DAG image is built FROM this base, so pinning base_image freezes your DAG on whatever the base was on the day you pinned it.

Defaults

Every field in leoflow.yaml is optional. Zero-valued fields are filled by LeoflowConfig.ApplyDefaults() (internal/domain/config.go) from the values declared in leoflow-yaml-schema.json. Defaults are hardcoded for v1; making them workspace-configurable is a v2 roadmap item.

Server environment (LEOFLOW_*)

This page is hand-maintained against the server’s configuration struct and default map in internal/config/server.go — treat that source as the final authority. Every LEOFLOW_* variable maps to a config key by upper-casing it and replacing . (and -) with _: e.g. auth.oidc.client_id → LEOFLOW_AUTH_OIDC_CLIENT_ID. The same keys can be set in a YAML config file or the Helm chart’s values.yaml.

Values resolve in increasing order of precedence — a later source overrides an earlier one:

flowchart LR
  D["Built-in defaults<br/>(serverDefaults)"] --> C["Config file<br/>(YAML)"]
  C --> E["LEOFLOW_* env vars"]
  E --> F["CLI flags"]

The Edition column reads both (Lite and Pro), Pro (Pro / Kubernetes topologies only), or dev-only. leoflow lite sets the dev-appropriate values automatically (isolated DB, port 8088, admin login on, no Redis).

Map- and list-valued keys (CORS origins, OIDC role/tenant maps, allowed email domains, …) are set from a config file or Helm values, not from a single env var — viper does not split one env var into a map or list.

Server (server.*)

Database (database.*)

Redis (redis.*)

Auth (auth.*)

OIDC / SSO (auth.oidc.*)

Read only when LEOFLOW_AUTH_PROVIDER=oidc, which is Pro-gated (ui.edition: pro) and fails boot closed unless issuer, client_id, and redirect_url are all set. Verification is keyless — the ID token is validated against the issuer’s public JWKS — so no secret is stored for the verify path.

Scheduler (scheduler.*)

Executor (executor.*)

Executor task defaults (executor.defaults.*)

Lowest-precedence (L0) per-cluster task defaults, applied at dispatch to fill gaps the DAG artifact left empty (ADR 0023). They never override a value baked into dag.json, keeping the artifact portable across clusters.

Warm worker pools (execution.*)

Pro-gated N:1 pod reuse (ADR 0058). Every field is operator-set. The default is a byte-for-byte no-op — warm pools OFF means a dedicated pod per task attempt.

Logs (logs.*)

External secrets (secrets.*)

Operator-only (ADR 0060): delivered to the task pod as LEOFLOW_SECRETS_*, which an author’s task env can never set. Empty backend keeps the Leoflow vault as the only source — byte-identical to having no external secrets at all. See External secrets and run the cluster validation runbook before enabling it in production.

Observability (observability.*)

UI (ui.*)

Trusted proxies and the client IP

By default Leoflow trusts no proxy: X-Forwarded-For is ignored and the client IP (used by the login rate-limiter and the audit log) is the direct peer. This is the safe default — it stops a spoofed X-Forwarded-For from forging the client IP — and is correct for Lite (exposed directly) and for any deployment reached without a reverse proxy.

When the API runs behind a reverse proxy or ingress, set server.trusted_proxies (env LEOFLOW_SERVER_TRUSTED_PROXIES) to the proxy’s IP or CIDR — e.g. your ingress controller’s pod CIDR. Only then is the left-most X-Forwarded-For entry honored, so rate-limiting and audit see the real client instead of the proxy. Do not set this to a broad private range (e.g. all of 10.0.0.0/8) in a cluster where task pods run: a task pod inside that range could then spoof the client IP. Scope it to the ingress. An invalid value fails secure (trust none) with a logged error.

The value is a list. Via the env var (the Helm chart’s only override path — it ships no server config file) set it comma-separated, e.g. LEOFLOW_SERVER_TRUSTED_PROXIES=10.0.0.0/8,192.168.1.1; viper splits it back into a list. In the chart set the config.trustedProxies value (a YAML list) and it is rendered comma-joined for you. In a config file it is an ordinary YAML list.