Secrets & Vault

CUGA reads secrets at runtime from one of two backends:

1. Local — environment variables (with optional UI overrides stored encrypted on disk).
2. 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 = false

VAULT_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 = false

Set to true only if you intend to manage secrets through CUGA's UI — most deployments should leave this off.

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_URL

This pattern works whether secrets ultimately come from os.environ or are injected by Vault.