Configuration

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

dexaflow.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/dexadata/dexaflow-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 dexaflow-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; dexaflow validate, dexaflow compile and dexaflow 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.

Which base you get when you do not pin one

When base_image is unset, dexaflow compile --build writes the FROM itself, and it chooses between two tag shapes based on the CLI you are running:

• a released dexaflow pins dexaflow-runtime:py<ver>-v<X.Y.Z>, which is immutable, so a compile from that release reproduces byte for byte (ADR 0003)
• a development build, from source or a dirty tree, falls back to dexaflow-runtime:py<ver>, a line every release republishes

So two people compiling the same project can end up on different bases if one runs a released CLI and the other runs one built from source. Setting base_image explicitly overrides both rules and is used verbatim. The full tag scheme for every published image is in Published images.

Which interpreter reads your DAG

python_version is a statement about the interpreter your DAG runs on, and the cluster honours it through the task base image. Every local tool that reads your dag.py honours it too, because a tool that judges your code with a different minor gives the wrong answer in the most confusing direction: type Alias[T] is valid from 3.12 and a SyntaxError on 3.11, so a 3.11 checker rejects a DAG the cluster runs correctly, and phrases it as a mistake in your code.

Three things follow from this that are worth knowing:

• Only an older interpreter is refused, not every different one. Python’s grammar grows, so a 3.11 checker rejects valid 3.13 code while a 3.13 checker accepts valid 3.11 code. Refusing every mismatch would have been the larger bug: dexaflow init writes python_version explicitly, so every scaffolded project takes this path, and most hosts carry a newer python3 than the 3.11 it writes.
• A skipped check is reported, never silent. When only an older interpreter is around, validate would rather tell you it could not check than hand you an answer it does not trust. Install the named minor, or run dexaflow setup, to turn the check back on. Your dexaflow.yaml is validated either way.
• The fallback is not as strict as the declared minor. Checked under a newer interpreter, syntax that only the newer one accepts passes here and then fails on the task image. Installing the minor you declare is what makes the check exact; the fallback only guarantees that what it rejects is genuinely wrong.
• dexaflow compile does not honour it yet. The parser executes your dag.py, so its own interpreter decides which syntax is legal, and today that is whichever interpreter dexaflow setup baked into parser_cmd. A project declaring a newer minor can still see a SyntaxError from compile for code the cluster runs (#1095). Running dexaflow setup under the minor you declare is the workaround.
• The three exemptions are the same everywhere. A version you never wrote is not a statement (the default applies), a declared base_image makes the field inert because you chose the FROM by hand, and a deprecated version warns rather than demanding you install an interpreter we are asking you to leave.

Values that reach the generated Dockerfile

Every value the generated Dockerfile interpolates is checked, because the Dockerfile format and Docker’s own operand lexer give some characters a meaning no quoting can take away. The refusal always names the field and the value, since a stray control character in YAML is invisible in the source.

The check is part of validating dexaflow.yaml, so every command that reads the file runs it: dexaflow validate, dexaflow compile with or without --build, dexaflow deploy and dexaflow lite. It used to run only while --build was rendering the Dockerfile, so validate called such a project valid and the refusal first appeared on the machine about to build the image.

Refused everywhere: a line break, a vertical tab or a form feed. These end a Dockerfile instruction or split it into new words, so a value carrying one closes the instruction it sits in and whatever follows becomes an instruction of its own. Docker splits a line on [\t\v\f\r ]+, which is why the vertical tab and form feed count alongside the newline. This covers base_image in the FROM; dbt.project, dbt_groups.*.project, dag_source and include_paths in their COPY lines; exclude_paths in the generated .dockerignore; and the dependencies and system_packages entries that already had the guard.

Refused in a COPY path: ', ", \, $ and <. After a Dockerfile is parsed, every COPY operand goes through a second pass that strips quotes, eats backslashes and expands $VAR. That pass runs whatever quoting the line used, so COPY ["d'a't.py", "..."] copies dat.py, not the file you named. None of these can be quoted into safety, so they are refused rather than silently copying the wrong path.

Refused in a COPY path: <. A different mechanism, not the operand lexer: COPY is heredoc-capable, so COPY <<EOF opens a heredoc that swallows the rest of the generated Dockerfile and then fails on the missing terminator.

This is a breaking change if one of those characters is already in your dag_source, dbt.project, dbt_groups.*.project or include_paths. An apostrophe in a directory name is not exotic. Such a project used to build, but it was copying the wrong path into the image the whole time: raw/$schema expanded to whatever the base image set, and sql\queries copied sqlqueries. dexaflow validate and dexaflow compile now fail and name the field, which is the point.

Refused in base_image: any whitespace, and ', ", \ and $. An image reference cannot contain any of them. FROM has no quoting, so whitespace makes the rest of the line read as the FROM <image> AS <stage> form. And FROM’s operand goes through the same lexer as a COPY path, so the other four rewrite the reference: runtime:v1$SUFFIX pulls runtime:v1 (with only a warning about an undeclared build argument), runtime:v'1' and runtime:v\1 pull runtime:v1 with no warning at all, and a stray " fails the build. The build would run your tasks on a different image than the one base_image names. Everything a reference can legally hold (a registry host and port, a path, a tag, a @sha256: digest) is accepted unchanged.

Refused in a COPY path: a leading --, which Docker reads as one of COPY’s own flags rather than as a path.

A path containing a space or a tab, or starting with [, is legal and is quoted rather than refused. Paths without any of those keep rendering exactly as before, so a project’s generated Dockerfile does not change because this guard exists.

exclude_paths is checked on the patterns that are actually emitted, not on the field alone: a dbt project path reaches the same .dockerignore through the build-artifact exclusions Dexaflow adds for it, so checking only the field left the class reachable through dbt.project and dbt_groups.

The same guards apply to the Dockerfile dexaflow lite --executor=k8s generates when a project ships none. That one writes <project>/Dockerfile and leaves it there, and a project-supplied Dockerfile is afterwards used verbatim, so a value that slipped through there would outlive the command that wrote it.

Rotating the encryption key

DEXAFLOW_SECRET_KEY takes a comma-separated list. The first entry encrypts and decrypts; every later entry only decrypts, and nothing is ever written under one. It is the same rule as Airflow’s fernet_key.

DEXAFLOW_SECRET_KEY="<new key>,<old key>"

The control plane re-encrypts the stored connection secrets onto the first key at startup and logs how many it moved. Only when that pass moved every row it found, with none changed underneath it by a concurrent write and none that no key opens, does it log the rotation as complete:

secret key rotation complete for the stored connections re_encrypted=7

Remove the old entry once every replica has started with the list. Until then it is still required, because a replica that has not restarted is still reading rows only the old key opens.

A row that no configured key can open is left untouched and reported at ERROR. Its ciphertext is the only copy of that credential, so the rotation never overwrites or deletes it; put the missing key in the list and restart. Until then the server logs a warning naming the connection, and:

• the connections list (GET /api/v2/connections) still returns every connection of the tenant, and shows this one with extra set to null and extra_unreadable: true, so the Admin Connections page still opens it;
• reading it alone (GET /api/v2/connections/<connection_id>), or updating it (saving it from the Admin page included), answers 500 with a message that names the connection, and its stored extra is left as it is;
• delivery to a task pod skips it with a warning, so only the tasks that use it fail.

If the old key is lost, delete the connection and set it again.

Trying keys in order is safe because AES-256-GCM is authenticated: a wrong key fails to open rather than returning plausible garbage.

dexaflow lite migrate-key --dry-run   # what it found and what it would do; writes nothing
dexaflow lite migrate-key             # asks before it changes anything

Encrypting Variables

Connection secrets are always encrypted at rest. Variables are stored in plaintext by default, and masked in API responses only when the key name looks secret (password, token, api_key, …). A Variable that holds a DSN, a webhook URL or an API key under another name is therefore readable in the database and in every backup of it.

Set DEXAFLOW_VARIABLE_ENCRYPTION=on (or LEOFLOW_VARIABLE_ENCRYPTION, or variable_encryption: on in dexaflow.yaml/leoflow.yaml) to encrypt them with the same key and cipher as connections:

• every write stores the value encrypted;
• at startup the server encrypts the Variables already stored in plaintext and logs how many it changed;
• reads, the API and delivery to task pods return the plaintext, so DAGs see no difference. The API reports is_encrypted: true for an encrypted Variable; masking still follows the key name;
• a key rotation and dexaflow lite migrate-key move encrypted Variables onto the new key together with the connection secrets.

on needs a usable DEXAFLOW_SECRET_KEY: without one the server refuses to start rather than keep storing plaintext. With the default off, an install without a key works as before. A Variable that no configured key opens (after a rotation that dropped the old key, for example) is left as it is, and the server logs a warning naming it:

• the Variables list (GET /api/v2/variables) still returns the tenant’s other Variables, and shows this one with its value masked (***) and value_unreadable: true;
• reading it alone (GET /api/v2/variables/<key>) answers 500 with a message that names the Variable;
• delivery to a task pod skips it with a warning, as it does for a connection.

To recover, add the key it was encrypted with back as a later DEXAFLOW_SECRET_KEY entry, or delete the Variable and set it again.

A value cannot start with dexaflow:enc:v1:, the tag that marks an encrypted value, in any mode.

Defaults

Every field in dexaflow.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 (DEXAFLOW_*)

The tables in this section are generated from the server’s configuration struct and default map in internal/config/server.go, so they list every key the server reads, with its real default. Every DEXAFLOW_* variable maps to a config key by upper-casing it and replacing . (and -) with _: e.g. auth.oidc.client_id → DEXAFLOW_AUTH_OIDC_CLIENT_ID. The same keys can be set in a YAML config file. The Helm chart models many of them as values, but not all: a key with no chart value has to go through extraEnv. The two OIDC maps below are the exception in both directions: no env var can carry them, so extraEnv is not a route, and the chart delivers them by writing a partial config file into a mounted ConfigMap (auth.oidc.tenantClaims, auth.oidc.roleMappings).

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["DEXAFLOW_* env vars"]
  E --> F["CLI flags"]

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

List-valued keys (CORS origins, OIDC scopes, allowed email domains, break-glass emails, trusted proxies) DO come from a single env var: viper’s decode hook splits a comma-separated value into a list, so DEXAFLOW_AUTH_OIDC_SCOPES=openid,email works. That is how the Helm chart sets them, since it ships no server config file. In a config file they are ordinary YAML lists.

Map-valued keys do not. auth.oidc.role_mappings and auth.oidc.tenant_claims are read only from a YAML config file, because their keys may contain dots (an IdP group name, a Google Workspace domain) and a dotted key is ambiguous in both env and viper’s own key space. The chart sets them through auth.oidc.tenantClaims and auth.oidc.roleMappings, which it renders into a ConfigMap mounted as the server’s DEXAFLOW_CONFIG file, with the keys quoted so a dotted domain survives (#1143). That file is deliberately partial: it carries only these two keys, so it can never override a setting the chart delivers as an env var.

In the tables below, the Variable column tells you which of these two groups a key is in: a row with a DEXAFLOW_* variable binds from that variable (and so from extraEnv or a chart value that sets it); a row that reads (config file only) (e.g. auth.oidc.role_mappings) can only be set in the config file. The Key column is the same setting’s path in that file.

Server (server.*)

Database (database.*)

Redis (redis.*)

Auth (auth.*)

OIDC / SSO (auth.oidc.*)

Read only when DEXAFLOW_AUTH_PROVIDER=oidc, which is Pro-gated (ui.edition: pro) and fails boot closed unless issuer, client_id, redirect_url and the tenant pin (tenant_claim + tenant_claims) are all set. The pin is in that set because every login resolves a tenant from it and an absent or unmapped claim value fails the login closed, never falling back to default, so a deployment without it boots green and rejects 100% of logins (#1143). tenant_claims is a map, so it loads only from the YAML config file named by DEXAFLOW_CONFIG; no env var can carry it. A blank name on either side of an entry in tenant_claims or role_mappings fails boot: corp.example: with nothing after it is valid YAML that binds to the empty string, and it would deny every login it governs while looking like a key you had filled in. Verification is keyless (the ID token is validated against the issuer’s public JWKS), so no secret is stored for the verify path.

Every key in this section has a modeled Helm value under auth.oidc.*, off by default (auth.oidc.enabled: false, which renders nothing at all). The chart sends the scalars and lists as DEXAFLOW_AUTH_OIDC_* env vars, the two maps as a mounted config file, and the client secret through the chart-managed Secret or auth.oidc.existingSecret. It refuses to render an enabled: true block that lacks the tenant pin. See the chart README’s SSO section and helm/dexaflow/examples/values-oidc-google.yaml.

DAG registration

Cluster deploy defaults (deploy.defaults.*)

What dexaflow deploy uses on this cluster for whatever the project, its workspace, its target and the person’s CLI config leave unset. The server serves them on GET /api/v2/deployDefaults; unset, it advertises nothing and every deploy resolves as before. They are not secrets: never put registry credentials here. The task service account and the warm pools are the server’s own settings, advertised when their switch is on. The server refuses to start with a value no deploy could use. See Cluster deploy defaults.

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.

Source mode (execution.source_mode.*)

Pro runs a DAG version straight from the dag.py it was registered with, with no image build (ADR 0067). A version runs in source mode when the mode is on, its image is exactly the runtime image below, and it carries a source. Every other version runs as before. See Source mode for what a source-mode DAG can and cannot do.

Logs (logs.*)

External secrets (secrets.*)

Operator-only (ADR 0060): delivered to the task pod as DEXAFLOW_SECRETS_*, which an author’s task env can never set. Empty backend keeps the Dexaflow 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.

Retention (retention.*)

The retention janitor deletes metadata rows past an age you choose, per data class. Every class is off by default (0 days): a default install never deletes a row. It runs on the scheduler leader only and rechecks leadership before every batch. A run is eligible once it settled (success or failed) more than dag_runs_days ago, every task instance of it is settled (success, failed, skipped or upstream_failed; a task in none is waiting to be scheduled, for example after a clear, so its run is kept), no staging volume of it is still live, and it is not the newest run of its DAG. The newest run (by logical date) is always kept, however old: the scheduler reads a DAG’s last logical date from it, and without it a scheduled DAG would run its latest slot again, or its whole history with catchup. An eligible run goes with its task instances, attempt history and XCom index rows, children first. Every batch is one short transaction of at most batch_size rows, run rows included; a run with more rows than that is finished by later batches, each of which checks again that the run is still eligible. A run’s task instances are deleted all together or not at all, so a clear between two batches never re-opens a run missing some of its tasks (a run whose task instances are all gone re-runs from scratch); a run with more task instances than batch_size has them removed alone in one batch, which is the only time a batch exceeds it. Before deleting, a batch locks the task instances of its runs and checks them again, so a run a clear touched after it was selected is kept whole; a run a clear is writing at that moment is skipped until a later cycle instead of waited on. Active and recent runs are never touched. The janitor sleeps batch_pause between batches and a cycle stops once it deleted max_rows_per_cycle rows; the rest waits for the next cycle. Each tenant’s runs and each tenant’s audit rows take turns, one batch each, so no tenant and neither class waits behind another’s backlog. Every cycle that deletes audit rows writes a retention.purge audit entry in the same scope with the row count and the cutoff. Turn on dry_run first to see what a cycle would delete: it only counts (summed across all tenants, at most 10000 runs and 10000 audit rows per tenant, so its cost stays bounded; the log says lower_bound=true when a tenant reached that cap), logs the counts and sets dexaflow_retention_rows_eligible, which a deleting cycle resets to zero. Metrics: dexaflow_retention_rows_deleted_total{table}, dexaflow_retention_rows_eligible{table} and dexaflow_retention_cycle_duration_seconds. What the janitor does not delete: task logs, which the disk log backend prunes after 30 days and an object store keeps by its bucket lifecycle policy, and the bookkeeping rows of staging volumes already marked deleted. The chart has no values for these keys; set them through extraEnv.

Observability (observability.*)

UI (ui.*)

Branding the UI

The bundled UI reads its look from theme in /ui/config, so a theme changes colors, fonts and the navigation icon without touching the bundle. This example uses a blue brand palette and the Outfit and JetBrains Mono fonts, and loads the fonts from Google Fonts:

ui:
  theme:
    tokens:
      colors:
        brand:
          "50":  { value: "#eff6ff" }
          "100": { value: "#dbeafe" }
          "200": { value: "#bfdbfe" }
          "300": { value: "#93c5fd" }
          "400": { value: "#60a5fa" }
          "500": { value: "#3b82f6" }
          "600": { value: "#2563eb" }
          "700": { value: "#1d4ed8" }
          "800": { value: "#1e40af" }
          "900": { value: "#1e3a8a" }
          "950": { value: "#172554" }
      fonts:
        heading: { value: "Outfit, system-ui, sans-serif" }
        body:    { value: "Outfit, system-ui, sans-serif" }
        mono:    { value: "'JetBrains Mono', ui-monospace, monospace" }
  stylesheetUrls:
    - "https://fonts.googleapis.com/css2?family=Outfit:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap"

Set all eleven brand shades: the UI uses different shades for buttons, selections and the navigation highlight, on the light and the dark theme. The UI only exposes part of its styling through the theme; anything else is a globalCss rule, and holds only as long as the bundle keeps the selector it targets.

Trusted-issuer handoff

When Dexaflow is part of a larger platform that already signs its users in, the platform can open a Dexaflow UI session for them without Dexaflow storing a password and without the platform holding Dexaflow’s signing secret:

1. The platform’s issuer signs a short-lived JWT with its own key, carrying iss, aud, sub, iat, exp, a unique jti, the tenant claim and, optionally, email. It publishes the public key as a JWKS.
2. The browser posts that token to POST /api/v2/auth/session as the form field token, with the page to open as next (a same-origin path), from a page on one of allowed_origins. An auto-submitting form is the usual way, because a token in a URL ends up in logs and history.
3. Dexaflow verifies the token, finds the active user linked to (issuer:<name>, sub) in the token’s tenant, sets the same session cookie a password or SSO login sets, and redirects to next with 303.

The token never creates a user and never grants roles: the user must already exist and be linked to the issuer, and its roles are the ones Dexaflow holds. Refusals set no cookie and answer 400 (no token), 401 (token rejected), 403 (origin not allowed, or no active linked user in that tenant), 429 (more than 30 posts a minute from one address) or 500, with the reason in the server log and the audit trail (issuer.login.success / issuer.login.failure), never in the response body. With an external sign-in URL set, only a stable code reaches the browser, as described next.

With DEXAFLOW_AUTH_EXTERNAL_SIGNIN_URL set, a refusal sends the browser back to that URL with 303 See Other instead of leaving it on a JSON error page, with a stable error code appended to the URL’s own query (https://portal.example.com/sign-in?lang=pt-BR&error=user_not_linked). Your page can show a message for the code; it must not post a new token on its own when error is present, or a lasting refusal becomes a redirect loop. The parameter is not authenticated: anyone can link to your page with any ?error= value, so map the known codes below to fixed messages and never print the value back. An error parameter already in the configured URL is replaced, not duplicated. Request metrics and traces count a redirected refusal under the status it stands for (dexaflow.refusal_status on the span), not as a 303.

A JWKS outage writes no issuer.login.failure audit row: the token was never checked, so it is not a failed sign-in. It is logged at error level instead.

The code is the only thing added to the URL: never the token, the subject, the email, the tenant or the origin. The redirect always goes to the configured URL and nowhere a request names. The audit event and the server log are the same either way, and the request’s log line keeps the refusal’s status as refusal_status and its level. A caller whose Accept asks for application/json or application/problem+json and not text/html is a script rather than a browser, and keeps the problem response with the status above even with the URL set.

Only pages on allowed_origins can post a handoff: browsers send Origin on every cross-site form post, and Dexaflow refuses any other, so a page elsewhere cannot sign a visitor in as someone else. A token must also have been issued no later than a minute from now and live no longer than max_lifetime_seconds (120 seconds unless set, at most 600). Each token opens one session: a second post of the same jti is refused until the token expires. That memory is per server process, so with several replicas a token could be accepted once by each; the short lifetime is what bounds that window. Mint each token right before posting it, and never put one in a URL.

Binding sessions to tenant hosts

When you serve each tenant on its own host (acme.example.com, globex.example.com) in front of one Dexaflow, set host_pattern so a session works only on its own tenant’s host:

auth:
  trusted_issuer:
    # ... the handoff keys above ...
    host_pattern: "{tenant}.example.com"

With it set:

• A handoff is accepted only when the request’s host is the pattern with the token’s tenant in place of {tenant}. On any other host it answers 403 (or redirects to the external sign-in with error=host_tenant_mismatch when one is set), sets no cookie, and records issuer.login.failure with reason host_tenant_mismatch.
• A request that authenticates with the session cookie is accepted only on the host of the session’s tenant, however the session was opened (handoff, password or single sign-on). On any other host the API answers 401 and the UI sends the browser to sign in, and both clear the cookie. A password or single sign-on login for the default tenant then works only on default.example.com (with the pattern above).
• A token in the Authorization header (the CLI, API clients, a trusted-issuer bearer) is not bound to a host: it never travels on its own the way a cookie does.

The host is the request’s Host header, compared without the port unless the pattern names one, and ignoring case. Behind an ingress that rewrites Host, list the ingress in server.trusted_proxies: the X-Forwarded-Host it sets is then used, and only from those peers. This also stops a session that a page on one tenant’s host plants for its own tenant from being used on another tenant’s host.

Trusted-issuer bearer tokens

A client that calls the API itself, such as a remote MCP client (ADR 0050 D9), sends a token on every request and cannot use the one-use browser handoff. With bearer_audiences set, the same trusted issuer can mint tokens for it:

auth:
  trusted_issuer:
    # ... the handoff keys above ...
    bearer_audiences: [leoflow-mcp]
    bearer_max_lifetime_seconds: 300   # 0 uses 900

A request whose Authorization: Bearer token is not one Dexaflow signed is checked against the issuer’s JWKS: signature, iss, an aud listed in bearer_audiences and not the handoff audience, exp, an iat no later than a minute from now, exp - iat within bearer_max_lifetime_seconds, a sub, and an allowed tenant. There is no jti rule: the token is reused until it expires. On every request Dexaflow then reloads the active user linked to (issuer:<name>, sub) in the token’s tenant, with the roles Dexaflow holds, so deactivating or unlinking the user ends its access on the next request, whatever the token’s expiry.

Anything wrong answers 401, the same as a bad Dexaflow token; the reason stays in the server log. A token that does not name the issuer and a bearer audience is refused before any signature check. When the token could not be checked at all, because the issuer’s JWKS or Dexaflow’s user store is unreachable, the answer is 503, so the client retries instead of signing in again. A token that verified but names no active linked user in its tenant is also recorded in the audit trail as issuer.bearer.failure. The bearer is read from the Authorization header only, never from the session cookie, and a handoff token is never accepted as a bearer, nor a bearer as a handoff.

Dexaflow caches the issuer’s keys and downloads the JWKS again only when a token names a key it does not hold, at most once every 30 seconds, for the handoff and the bearer together. A forged token therefore cannot make Dexaflow call your issuer on every request. After you rotate keys, tokens signed with the new key can be refused for up to 30 seconds; publish the new key in the JWKS before you sign with it.

Keep bearer tokens short-lived. Dexaflow cannot revoke one before it expires, only the user behind it; an MCP gateway that mints one per client for a few minutes and caches it is the intended shape.

Scopes

A bearer token’s scope claim, a space-separated string as in RFC 9068, narrows what it may do (ADR 0067), so a user can grant a client less than their own rights:

• The scope check runs after the role check, and both must pass. A viewer’s token with dexaflow:run still cannot trigger.
• No scope implies another, with one exception: dexaflow:deploy opens the reads a deploy makes (listed above). A client that runs and reads needs both.
• A token without a scope claim may only read. A claim that is not a string is refused with 401.
• Every other write (connections, variables, pools, users, deleting a DAG or a run, the IDE) is refused to a bearer token whatever its scopes. Use the UI or a Dexaflow token for those.
• Routes that check no permission of their own (the UI’s dashboard and menus, /ui/auth/me, and the screens Dexaflow only stubs) are refused to a bearer token whatever its scopes, so a route added without a permission check never ignores a token’s scopes.
• A refusal is 403 with a detail that names the missing scope.
• The same scopes narrow Dexaflow’s own API tokens (dexaflow auth create-token --scope deploy, ADR 0074): a deploy token carries dexaflow:deploy alone. See credentials for the control plane.
• Pausing and unpausing is PATCH /api/v2/dags/{id} with {"is_paused": true} or false. A body without is_paused is refused with 400 rather than read as an unpause.

Dexaflow tokens and the sessions the browser handoff opens carry no scopes; only their roles decide.

Deploys through the issuer only

An operator whose deployments belong to a platform (a CD system, a review-and-approve service) can make that platform the only way to deploy, so nobody skips its checks and audit by calling the API directly. Set a deploy audience, minted by the issuer for that platform only:

auth:
  trusted_issuer:
    # ... the handoff keys above ...
    deploy_audience: dexaflow-deploy

Then POST /api/v2/dags/{id}/versions, its dry run (POST /api/v2/dags/{id}/versions/dry_run), PUT /api/v2/dags/{id}/currentVersion (rollback) and DELETE /api/v2/dags/{id} (an undeploy) accept only a bearer of the trusted issuer whose aud is deploy_audience alone and that carries dexaflow:deploy, and the linked user’s roles must still allow it (deploy or write on dags; write on dags to delete). Every other credential is refused with 403, a detail saying that deploys go through the trusted issuer and the header Dexaflow-Deploy-Via: trusted-issuer, whatever its roles and scopes: a UI session, a password login token, an API token (dexaflow auth create-token --scope deploy included), a bearer of one of the bearer_audiences, a token whose aud names the deploy audience next to another audience, the session a handoff opens, and the auth.dev_no_auth principal. dexaflow deploy turns that 403 into a message that says so. Reads, run control and every other route are unchanged. Pausing and unpausing a DAG (PATCH /api/v2/dags/{id}) stays under roles and the dexaflow:run scope on purpose: it is run control, not a deploy, so an operator can still stop a DAG without the platform.

• The deploy audience is a bearer audience of its own: it turns the bearer checks above on even with no bearer_audiences, and its tokens follow the same rules (lifetime, linked user, tenant, no jti rule).
• A deploy-audience token gets the scopes it carries, like any bearer. Mint it with dexaflow:deploy alone, so it reaches only the deploy routes and the reads a deploy makes; with more scopes it can do more, as any bearer can.
• A deploy token’s aud is the deploy audience alone (a string, or an array of that one entry). A token minted for the deploy audience and another bearer audience, such as [leoflow-mcp, dexaflow-deploy], is an ordinary bearer of that other audience and is refused on these routes, so the client it was minted for cannot deploy with it. Audiences are compared exactly, case included.
• deploy_audience must differ from audience and from every bearer_audiences entry, so neither a handoff token nor another client’s bearer is ever a deploy token, and has no surrounding spaces. The server refuses to start otherwise, and when the trusted issuer itself is not configured. The Helm chart refuses to render deployAudience without issuer.
• Nothing else registers a version or changes the current version: the UI’s version screens only read, and the MCP server has no deploy tool (it reads and controls runs through the same API with its client’s token).

Operator service API

An operator that serves several organizations from one Dexaflow (a hosting provider, an internal platform team) creates tenants and their users from its own automation instead of writing to the database. With auth.service_token set, two idempotent endpoints accept Authorization: Bearer <service token>; a user session never reaches them.

PUT /api/v2/service/tenants/{tenant} with an optional {"display_name": "Acme Corp"} creates the tenant (1-63 lowercase letters, digits or -) with the same built-in roles, role permissions and default pool as the default tenant, copied from it so every tenant’s ladder stays equal. It answers 201 when the tenant is new and 200 when it already existed; a second call fills in anything missing and, apart from default_pool_slots below, changes nothing else.

The same body may carry "default_pool_slots": 8 to size the tenant’s default_pool, the slot cap every task without an explicit pool shares within the tenant. Without it a new tenant gets the default tenant’s size (128 unless an operator changed it), which on an engine shared by many tenants lets each of them run that many tasks at once. Given on a later call, it re-sizes the existing pool, including a size a tenant admin set through the pools API, so an automation that re-applies its tenants should send the size it wants to keep; left out, the pool is not touched. It must be a whole number from 1 to 2147483647 (400 otherwise), and the audit entry records it. It sets the pool’s size, not a ceiling on the tenant: a tenant role that may write pools (operator, admin) can still resize it or create other pools. Pools apply to the Pro edition only; Lite ignores the value.

The same body may also carry tenant limits, each a whole number from 0 to 2147483647 (400 otherwise), where 0 means unlimited:

A tenant created without limits has none, and a later call changes only the limits it carries: one left out keeps its value, so existing automation that sends only display_name or default_pool_slots is unaffected. The audit entry records each limit given.

A request a limit refuses answers 403 with a detail that names the limit, for example the tenant reached its limit max_runs_per_day of 50 for today (UTC). A scheduled run the daily limit refuses is skipped, not failed: the scheduler logs one warning per tenant and day and counts it in dexaflow_scheduler_decisions_total{decision_type="tenant_daily_run_cap"}, and the slot is created on a later tick once the UTC day turns (with catchup, the slots missed in between are created too, and count against the new day).

How each limit is measured:

• The daily run count is kept on the tenant and charged in the same transaction that creates the run, so concurrent triggers can never take the tenant past the limit, and deleting a DAG or a run does not give runs back. Counting starts when the limit is set; runs created earlier that day do not count.
• The schedule gap is computed from the cron expression: the shortest gap between consecutive fire times inside a day and across days, including the days it skips (0 9 * * 1-5 is 24 hours, 0,59 0,23 * * * is one minute, across midnight). @every <duration> is its duration. Manual DAGs, @once and @continuous are not limited. Times are UTC; with CRON_TZ, the two days a year the clocks change differ: a gap that spans the change is an hour shorter or longer, a time inside the repeated hour fires twice, one hour apart (30 1 * * * in Europe/London fires at 00:30 and 01:30 UTC on the last Sunday of October), and a time inside the skipped hour does not fire that day.
• max_task_pool_slots compares each task’s pool_slots (1 when unset). A platform that sizes each tenant’s default_pool_slots sets it to the same number, so a task that could never fit the pool is refused when it is pushed instead of waiting forever.
• max_dags counts the tenant’s DAGs. Two different new DAGs registered at the same moment while the tenant is one below the limit can both be accepted; it is checked, not locked, like max_active_runs.

Lowering a limit never removes anything: a tenant above a new max_dags keeps its DAGs (and can update them) but cannot add more, and a DAG whose schedule is now too frequent, or whose task is now larger than max_task_pool_slots, keeps running until its next registration.

PUT /api/v2/service/tenants/{tenant}/users/{subject} with {"email": "ana@acme.com", "roles": ["operator"]} makes sure a user with no password exists in the tenant, linked to the trusted issuer under that subject, with exactly those roles. It answers 201 for a new user and 200 for an existing one, whose roles it sets to the list given. It needs auth.trusted_issuer (409 otherwise), answers 404 for an unknown tenant, 422 for a role the tenant does not have, and 409 for a subject already linked in another tenant or an email already used by another user of the tenant, such as a password account. A tenant the trusted issuer may not sign in to (auth.trusted_issuer.allowed_tenants) is 403. The user signs in only through the trusted issuer’s handoff.

Every call that reaches the database is recorded in the audit trail, as service.tenant.ensure (with whether the tenant was created) and service.user.ensure (with the subject, email, roles and whether the user was created), each with outcome success or failure.

The service token is a root-level credential: whoever holds it can create tenants and grant any role, admin included, in every tenant the trusted issuer covers. Keep it in a Secret, give it only to the automation that provisions tenants, and rotate it by changing the Secret and restarting.

Alert destinations

An on-failure alert (alerting) is posted by the control plane to the URL, with the headers, of a connection the DAG’s tenant manages. When tenants that do not trust each other share one engine, that URL is untrusted input: it can name the control plane’s own loopback, a private service in the cluster, or the cloud metadata endpoint.

Set scheduler.alerts.block_private_destinations: true (env DEXAFLOW_SCHEDULER_ALERTS_BLOCK_PRIVATE_DESTINATIONS, chart config.alerts.blockPrivateDestinations) to refuse those destinations. The check runs on the address the control plane is about to connect to, after DNS resolution, so a host name that resolves to an internal address is refused even if it resolved to a public one earlier (DNS rebinding), and every redirect hop is checked the same way (at most three redirects are followed). A NAT64 (64:ff9b::/96) or 6to4 address is checked as the IPv4 address it carries, so an IPv6-only cluster behind DNS64 still reaches a public IPv4-only endpoint. The block also covers the Azure host endpoint 168.63.129.16, which looks public but is node-local. With the block on, alert requests are dialed directly and do not use the HTTP_PROXY / HTTPS_PROXY environment, since through a proxy the real destination could not be checked. A refused alert is logged and counted as a failed delivery, like any other send error.

If an alert endpoint legitimately lives on a private network (an on-premises chat server, for example), list its range in scheduler.alerts.allowed_cidrs (chart config.alerts.allowedCIDRs). A range broad enough to include loopback or a metadata endpoint is accepted but logged as a warning at startup.

Trusted proxies and the client IP

By default Dexaflow 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 DEXAFLOW_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. DEXAFLOW_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.

Other environment variables

The variables below are read directly by one binary instead of through the config file, so they have no config key. Like every other variable, each also works with the LEOFLOW_ prefix.

Server process (dexaflow-server)

MCP server (dexaflow-mcp)

Each variable is the default of the flag named in its row; see the MCP server page.

CLI (dexaflow)

The CLI reads ~/.dexaflow/config.yaml (written by dexaflow auth login and dexaflow setup). Keys with a variable can also be set from the environment, which overrides the file; flags override both.

The CLI also reads these variables, which have no config key:

Set by Dexaflow on task processes

The control plane sets these on every task pod (or, in Lite, on every agent process) from the settings above. They are listed so you can recognize them when debugging a task; do not set them yourself.

Names from before the rename

Dexaflow was called Leoflow. Every name from that time keeps working, and none is scheduled for removal. When both the current and the old name are present, the current one wins.

A few internal names keep the old spelling on purpose, because renaming them would break running installations: the Postgres database names (leoflow, leoflow_dev), the Lite cluster (leoflow-dev), the leoflow.io/* labels and annotations on task pods, the LEOFLOW_* variables the control plane passes to task pods (agents built before the rename only read those), and the OpenTelemetry service name leoflow-server (traces stay continuous across the upgrade), and the internal Python modules leoflow_runtime and leoflow_parser (task images built before the rename run the former, and existing config.yaml files name the latter in parser_cmd).