Environment variable reference

Use this page to override gateway config values at process start. It documents supported variables, parse rules, and common failure cases.

How overrides work

1. Gateway loads built-in defaults.
2. Gateway applies ongoingai.yaml values when the file exists.
3. Gateway applies supported ONGOINGAI_* env vars last.

Env vars override YAML only when the env value is non-empty. If you set a variable to an empty string, gateway ignores it.

Supported variables

OpenTelemetry auto-enable behavior:

• If any OTEL exporter/service/sampler variable above is set, gateway enables OTEL by default.
• OTEL_SDK_DISABLED=true always disables gateway OTEL instrumentation.

Values without env overrides

The following config areas do not support env var overrides in this release:

• providers.*.prefix
• pii.stages.*
• pii.detectors.*
• pii.headers.denylist
• pii.body.key_denylist
• pii.replacement.format
• auth.keys
• limits.*

Type and validation behavior

• ONGOINGAI_PORT and ONGOINGAI_BODY_MAX_SIZE must parse as integers.
• ONGOINGAI_CAPTURE_BODIES and ONGOINGAI_AUTH_ENABLED must parse as booleans.
• OpenTelemetry bool fields (OTEL_SDK_DISABLED, OTEL_EXPORTER_OTLP_INSECURE) must parse as booleans.
• OpenTelemetry integer fields (OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_METRIC_EXPORT_INTERVAL) must parse as integers.
• OpenTelemetry sampling field (OTEL_TRACES_SAMPLER_ARG) must parse as float.
• OpenTelemetry exporter selectors (OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER) accept otlp or none.
• String variables are applied as-is, then checked by config validation.
• If a string override is invalid for the target field, ongoingai config validate fails with a field-specific error.

Examples:

• ONGOINGAI_STORAGE_DRIVER=invalid fails with: storage.driver must be one of sqlite, postgres.
• ONGOINGAI_OPENAI_UPSTREAM=api.openai.com fails with: providers.openai.upstream must include scheme and host.

Examples

Override server port for one command

ONGOINGAI_PORT=9090 ongoingai config validate --config ongoingai.yaml
ONGOINGAI_PORT=9090 ongoingai serve --config ongoingai.yaml

Enable Postgres without editing YAML

ONGOINGAI_STORAGE_DRIVER=postgres \
ONGOINGAI_STORAGE_DSN=POSTGRES_DSN \
ongoingai config validate --config ongoingai.yaml

Placeholder:

• POSTGRES_DSN: Postgres DSN, for example postgres://user:pass@db.example.com:5432/ongoingai?sslmode=require.

Enable gateway auth with a custom header

ONGOINGAI_AUTH_ENABLED=true \
ONGOINGAI_AUTH_HEADER=X-Internal-Gateway-Key \
ongoingai serve --config ongoingai.yaml

Verification workflow

1. Set one override and validate config:

   BashCopy

   ONGOINGAI_PORT=9090 ongoingai config validate --config ongoingai.yaml

2. Start the gateway with the same override:

   BashCopy

   ONGOINGAI_PORT=9090 ongoingai serve --config ongoingai.yaml

You should see a startup log line with port set to 9090.

Troubleshooting

invalid ONGOINGAI_PORT

• Symptom: ongoingai config validate fails before field validation.
• Cause: ONGOINGAI_PORT is not an integer.
• Fix: Set an integer value such as 8080 or 9090.

Invalid bool/float OTEL env values

• Symptom: Config load fails with an invalid bool env var error.
• Cause: A standard OTEL bool (OTEL_SDK_DISABLED, OTEL_EXPORTER_OTLP_INSECURE) or float (OTEL_TRACES_SAMPLER_ARG) env value does not parse.
• Fix: Use valid bool values such as true/false and decimal floats such as 0.25.

Env var set but value does not change

• Symptom: Gateway behavior still matches YAML.
• Cause: Env var is empty, so override is skipped.
• Fix: Set a non-empty env var value.

Expected env override is missing

• Symptom: You cannot override a field with env vars.
• Cause: That field does not have env mapping in this release.
• Fix: Set the value in ongoingai.yaml instead.

Next steps

• Config reference
• CLI reference
• Quickstart