Secrets & Vault
Resolve secrets from environment variables or HashiCorp Vault — with KV v1/v2 and Kubernetes auth.
CUGA reads secrets at runtime from one of two backends:
- Local — environment variables (with optional UI overrides stored encrypted on disk).
- Vault — HashiCorp Vault KV v1 or v2, with token or Kubernetes auth.
The backend is selected via [secrets].mode in settings.toml. See the full option list in the Settings reference.
Local mode (default)
[secrets]
mode = "local"
force_env = true
db_encryption_key_env = "CUGA_SECRET_KEY"When force_env = true, CUGA always resolves from os.environ and ignores any UI overrides. Set CUGA_SECRET_KEY in the environment to a stable encryption key — it is used to encrypt UI-provided overrides on disk when force_env = false.
Vault mode
Token auth
[secrets]
mode = "vault"
vault_addr = "https://vault.example.com:8200"
vault_auth_method = "token"
vault_token_env = "VAULT_TOKEN"
vault_mount = "secret"
vault_kv_version = "" # empty = KV v2
vault_secret_path = "cuga/prod"Then export the token:
export VAULT_TOKEN="hvs.CAESI..."Kubernetes auth
When CUGA runs in a Kubernetes pod, use the projected service-account JWT:
[secrets]
mode = "vault"
vault_addr = "https://vault.example.com:8200"
vault_auth_method = "kubernetes"
vault_k8s_role = "cuga"
vault_k8s_mount_path = "kubernetes"
vault_k8s_jwt_path = "/var/run/secrets/kubernetes.io/serviceaccount/token"
vault_mount = "secret"
vault_secret_path = "cuga/prod"The auth method, role, and secret path can also be set at runtime via DYNACONF_SECRETS__VAULT_AUTH_METHOD and DYNACONF_SECRETS__VAULT_SECRET_PATH.
TLS
If your Vault server uses an internal CA:
vault_cacert = "/etc/cuga/vault-root-ca.pem"
vault_skip_verify = falseVAULT_CACERT and VAULT_SKIP_VERIFY env vars also work. Do not disable verification in production.
Writing secrets back to Vault
By default, CUGA reads secrets only:
vault_write_enabled = falseSet to true only if you intend to manage secrets through CUGA's UI — most deployments should leave this off.
LLM credentials in Manage
The LLM panel can select Use saved secret, create a secret, and store its reference in the agent draft. A reloaded draft preserves the reference even though API responses redact secret values. Selecting a saved Vault reference does not copy its plaintext value into the model configuration.
force_env = true ignores UI overrides. The current UI model factory also treats mode = "local" as environment-driven: it uses the TOML provider and ignores db://, vault://, and aws:// credential references there. See LLM connections before switching providers or secret backends.
Referencing env-resolved secrets
When configuring tools (e.g. an Evolve MCP server), pass env://VAR_NAME placeholders so values are read from the process environment at runtime:
OPENAI_API_KEY=env://OPENAI_API_KEY
OPENAI_BASE_URL=env://OPENAI_BASE_URLThis pattern works whether secrets ultimately come from os.environ or are injected by Vault.
Never commit secrets to settings.toml or to git. Use environment variables, Vault, or your deployment's secret manager.
