Skip to main content

Environment Variable Patterns

Keeptrusts does not use one universal *_env rule across every config surface. Keeptrusts uses three distinct patterns today:

  1. secret_key_ref: { env: ... } for many secrets
  2. secret_key_ref: { store: ... } for provider targets that resolve from hosted secret records
  3. A small set of literal *_env fields such as public_key_env, secret_key_env, and url_env

Provider authentication​

Provider targets support both environment-backed refs and hosted secret-store refs.

providers:
  targets:
    - id: openai-local
      provider: openai
      model: your-openai-model
      secret_key_ref:
        env: KEEPTRUSTS_OPENAI_API_KEY

    - id: openai-hosted
      provider: openai
      model: your-openai-model
      secret_key_ref:
        store: KEEPTRUSTS_OPENAI_API_KEY
  • secret_key_ref.env is resolved from the gateway process environment.
  • secret_key_ref.store is accepted on provider targets and resolved by name through the connected gateway's hosted secret resolver. Create and manage the record with kt secret; the retired config-variable API is not this workflow.
  • Prefer a Keeptrusts-prefixed name such as KEEPTRUSTS_OPENAI_API_KEY for provider credentials. The reference is explicit—the gateway does not infer a provider credential from a conventional ambient name such as OPENAI_API_KEY.
  • Provider targets may omit secret_key_ref and still pass parsing. An ordinary auth-required target then remains inactive because no credential resolves; auth-optional and self-credentialed provider types use their own documented authentication path.

Env-only secret surfaces​

These config surfaces currently reject secret_key_ref.store and only accept env-backed secrets:

SurfaceSupported shape
policy.flagged-review.provider.secret_key_refsecret_key_ref: { env: ... }
policy.external-moderation.secret_key_refsecret_key_ref: { env: ... }
tool_validation.semantic_validation.secret_key_refsecret_key_ref: { env: ... }
tool_security.secret_key_refsecret_key_ref: { env: ... }

If you pass store on one of those surfaces, config validation returns ...store is not supported in this config surface.

Callback-specific env fields​

Callback config supports a mix of env-name fields and literal fallbacks:

Callback typeEnv-backed fields
langfusepublic_key_env, secret_key_env
datadogsecret_key_ref.env
heliconesecret_key_ref.env
braintrustsecret_key_ref.env
prometheusNo credential field

Example:

callbacks:
  - type: langfuse
    host: https://cloud.langfuse.com
    public_key_env: KEEPTRUSTS_LANGFUSE_PUBLIC_KEY
    secret_key_env: KEEPTRUSTS_LANGFUSE_SECRET_KEY

  - type: datadog
    secret_key_ref:
      env: KEEPTRUSTS_DATADOG_API_KEY
    site: datadoghq.com

The schema currently accepts a webhook callback and its signing_secret_env field, but the gateway callback router does not implement that callback type. It skips the entry as unknown and does not read the signing secret. Do not configure webhook callbacks until the runtime implements them.

Distributed rate-limit backend env fields​

Use the top-level distributed_rate_limit: block. Internal parser paths also recognize nested distributed: blocks, but the published schema and kt policy lint reject those placements. Runtime dispatch only builds a shared counter for global_rate_limit; it does not create distributed IP or token counters.

distributed_rate_limit:
  backend: redis
  url_env: KEEPTRUSTS_LLM_CACHE_REDIS_URL

If url_env is omitted, config loading defaults to KEEPTRUSTS_LLM_CACHE_REDIS_URL.

Execution-target env maps​

Execution targets use cli_env and adapter_env as literal key/value maps. Config loading does not expand ${VAR} placeholders inside these maps.

providers:
  targets:
    - id: browser-runner
      provider: browser
      adapter_command: /usr/local/bin/keeptrusts-browser-adapter
      cli_env:
        LOG_LEVEL: debug
      adapter_env:
        LOG_LEVEL: info
        PLAYWRIGHT_BROWSERS_PATH: /opt/playwright

Important behavior note:

  • values are copied as literal strings
  • on duplicate keys, adapter_env currently overwrites cli_env

Cloud/account-id helper fields​

A few integrations use dedicated env-name fields instead of secret_key_ref:

  • cloudflare_account_id_env
  • snowflake_account_identifier_env
  • public_key_env
  • secret_key_env
  • url_env

Treat these as field-specific exceptions, not as proof of a universal *_env convention.

Hosted secret-store references​

secret_key_ref.store names are resolved through the hosted secret API for a connected gateway. Use provider targets for this pattern, and create the named record with kt secret.

providers:
  targets:
    - id: shared-openai
      provider: openai
      model: your-openai-model
      secret_key_ref:
        store: KEEPTRUSTS_OPENAI_API_KEY

Replace your-openai-model with a model identifier available to your OpenAI account.

export KEEPTRUSTS_OPENAI_API_KEY="<provider-key>"
kt secret create \
  --name KEEPTRUSTS_OPENAI_API_KEY \
  --env-var KEEPTRUSTS_OPENAI_API_KEY

The gateway runtime token used to fetch a connected configuration and resolve its bound secrets is separate from the provider value stored in this record.

Next steps​