Environment Variables¶

$DEVENV_STATE refers to <project root>/.devenv/state — this is where devenv stores runtime data.

All settings can be overridden in .env. Defaults (where appropriate) are provided in devenv.nix at low priority so .env values take precedence.

file: prefix: Any env var can be prefixed with file: to read the value from a file at runtime (e.g. KLANGK_JWT_SECRET=file:/run/secrets/jwt). The file contents are stripped of leading/trailing whitespace. This works with secret management tools like agenix/sops that write decrypted secrets to files. If the file cannot be read, an error is logged and the value is treated as unset.

cmd: prefix: Any env var can be prefixed with cmd: to resolve the value by running a shell command at runtime and using its stdout (e.g. KLANGK_JWT_SECRET=cmd:aws secretsmanager get-secret-value --secret-id klangk/jwt | jq -r .SecretString). The stdout is stripped of leading/trailing whitespace. This lets values be fetched from external sources (vault CLIs, cloud secret managers, decryption tools) without materializing them to disk or a plain env var. The command runs via the shell (so pipes work) with a short timeout; only values an operator explicitly prefixes with cmd: are ever executed. If the command fails (non-zero exit, timeout, or execution error), an error is logged and the value is treated as unset.

Note: the prefixes are applied only where the backend reads a var through resolve_env_value/resolve_file_value (the vast majority of KLANGK_* vars). A couple of values are consumed out-of-band by nginx.sh via bash expansion (KLANGK_LLM_BASE_URL, KLANGK_LLM_API_KEY) — these are run through the klangk-resolve-value console script (see below) at nginx config generation time, so the prefixes work there too. A small number of vars are read raw by design (e.g. KLANGK_TRUSTED_PROXY_CIDRS, which is a public CIDR list, not a secret).

klangk-resolve-value console script: a CLI twin of resolve_file_value (registered as klangk-resolve-value = "klangk_backend._resolve_value:main" in src/backend/pyproject.toml) that resolves a single prefixed value from its single argument and prints the result to stdout (file: → file contents; cmd: → command stdout; plain → verbatim; failure → empty + reason on stderr). It is the single source of truth consumed by nginx.sh; operators rarely need to call it directly, but it is available on the PATH wherever the backend is installed:

klangk-resolve-value 'file:/run/secrets/jwt'
klangk-resolve-value 'cmd:aws secretsmanager ... | jq -r .SecretString'
klangk-resolve-value 'plain-value'   # -> plain-value (verbatim)