Skip to main content

Environment variable use

Verdictan does not use one *_env rule for all configuration surfaces. At this time, Verdictan uses three patterns:

  1. secret_key_ref: { env: ... } for many secrets
  2. secret_key_ref: { store: ... } for provider targets that use hosted secret records
  3. Literal *_env fields such as public_key_env, secret_key_env, and url_env

Provider authentication​

Provider targets support environment references and hosted secret references.

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

    - id: openai-hosted
      provider: openai
      model: your-openai-model
      secret_key_ref:
        store: VERDICTAN_OPENAI_API_KEY
  • The gateway resolves secret_key_ref.env from its process environment.
  • A provider target accepts secret_key_ref.store. The connected gateway resolves the name through its hosted secret resolver.
  • Create the hosted record with verdictan secret.
  • Manage the record with verdictan secret.
  • Use a Verdictan prefix, such as VERDICTAN_OPENAI_API_KEY, for a provider credential.
  • The gateway does not infer a provider credential from a standard environment name such as OPENAI_API_KEY.
  • A provider target can pass parsing without secret_key_ref. An ordinary target that must authenticate then is not active.
  • Providers with optional or self-contained credentials use their documented authentication method.

env-only secret fields​

These configuration surfaces reject secret_key_ref.store. They accept only environment secrets:

SurfaceAccepted structure
policy.flagged-review.provider.secret_key_refsecret_key_ref: { env: ... }
policy.external-moderation.secret_key_refsecret_key_ref: { env: ... }
policy.tool-validation.semantic_validation.secret_key_refsecret_key_ref: { env: ... }
policy.tool-security.secret_key_refsecret_key_ref: { env: ... }

If you use store on one of these surfaces, configuration validation returns ...store is not supported in this config surface.

Callback environment fields​

Callback configuration supports environment name fields and literal fallback values:

Callback typeEnv-backed fields
langfusepublic_key_env, secret_key_env
datadogsecret_key_ref.env
heliconesecret_key_ref.env
braintrustsecret_key_ref.env
prometheusThis type has no credential field.

Example:

callbacks:
  - type: langfuse
    host: https://cloud.langfuse.com
    public_key_env: VERDICTAN_LANGFUSE_PUBLIC_KEY
    secret_key_env: VERDICTAN_LANGFUSE_SECRET_KEY

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

Environment fields for rate limits​

Use the top-level distributed_rate_limit: block. The distributed backend shares only the global_rate_limit counter. It does not share IP, user, or token counters.

distributed_rate_limit:
  backend: redis
  url_env: VERDICTAN_LLM_CACHE_REDIS_URL

If you do not specify url_env, configuration loading uses VERDICTAN_LLM_CACHE_REDIS_URL.

Execution environment maps​

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

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

Map behavior:

  • The gateway copies values as literal strings.
  • For duplicate keys, adapter_env replaces cli_env at this time.

Account helper fields​

Some integrations use environment name fields, not secret_key_ref:

  • cloudflare_account_id_env
  • snowflake_account_identifier_env
  • public_key_env
  • secret_key_env
  • url_env

These fields are special cases. They do not define a shared *_env rule.

Hosted secret-store references​

A connected gateway resolves secret_key_ref.store names through the hosted secret API. Use this pattern only for provider targets.

Create the named record with verdictan secret.

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

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

export VERDICTAN_OPENAI_API_KEY="<provider-key>"
verdictan secret create \
  --name VERDICTAN_OPENAI_API_KEY \
  --env-var VERDICTAN_OPENAI_API_KEY

The gateway runtime token gets a connected configuration and resolves its bound secrets. This token is different from the stored provider value.

Next steps​