Config reference

Use this page to configure OngoingAI Gateway with ongoingai.yaml. It lists field defaults, validation constraints, and runtime behavior.

Load order and precedence

1. Gateway starts from built-in defaults.
2. If the config file exists, YAML values override defaults.
3. If supported ONGOINGAI_* env vars are set, env vars override YAML values.

If the config file path does not exist, startup still works with defaults and env overrides.

Baseline config

server:
  host: 0.0.0.0
  port: 8080
 
storage:
  driver: sqlite
  path: ./data/ongoingai.db
  dsn: ""
 
providers:
  openai:
    upstream: https://api.openai.com
    prefix: /openai
  anthropic:
    upstream: https://api.anthropic.com
    prefix: /anthropic
 
tracing:
  capture_bodies: false
  body_max_size: 1048576
 
observability:
  otel:
    enabled: false
    endpoint: localhost:4318
    insecure: true
    service_name: ongoingai-gateway
    traces_enabled: true
    metrics_enabled: true
    sampling_ratio: 1.0
    export_timeout_ms: 3000
    metric_export_interval_ms: 10000
 
pii:
  mode: ""
  policy_id: default/v1
  stages:
    request_headers: true
    request_body: true
    response_headers: true
    response_body: true
  detectors:
    email: true
    phone: true
    ssn: true
    token_like: true
  headers:
    denylist:
      - authorization
      - cookie
      - set-cookie
      - x-api-key
      - x-ongoingai-gateway-key
  body:
    key_denylist:
      - email
      - phone
      - password
      - token
      - secret
      - ssn
      - api_key
      - authorization
  replacement:
    format: "[{type}_REDACTED:{hash}]"
    hash_salt: ""
 
auth:
  enabled: false
  header: X-OngoingAI-Gateway-Key
  keys: []
 
limits:
  per_key:
    requests_per_minute: 0
    max_tokens_per_day: 0
    max_cost_usd_per_day: 0
  per_workspace:
    requests_per_minute: 0
    max_tokens_per_day: 0
    max_cost_usd_per_day: 0

Treat this baseline as a starting point. Most production deployments adjust auth, limits, and storage settings first.

Top-level configuration areas

• server: HTTP bind host and port.
• storage: Trace storage backend selection and connection fields.
• providers: Upstream endpoints and route prefixes.
• tracing: Request and response body capture controls.
• observability: OpenTelemetry exporter and sampling controls.
• pii: Storage redaction policy and detector behavior.
• auth: Gateway authentication header and key configuration.
• limits: Rate and daily usage limits by key and workspace.

Field reference

server

storage

providers

providers.openai and providers.anthropic share the same schema.

tracing

observability

pii

Validation:

• Allowed values for pii.mode: off, redact_storage, redact_upstream, block.
• All listed modes are supported in this release.
• In redact_upstream and block, provider-route request bodies are inspected within tracing.body_max_size and fail closed on policy-evaluation uncertainty.
• pii.scopes[].match must include at least one of: org_id, workspace_id, key_id, provider, route_prefix.
• pii.scopes[].match.route_prefix must start with / when set.
• pii.scopes[].mode, when set, must be one of off, redact_storage, redact_upstream, block.

auth

auth.keys[] fields:

Role defaults:

• owner, admin: proxy:write, analytics:read, keys:manage
• developer, member: proxy:write, analytics:read
• viewer: analytics:read

limits

Limit behavior:

• Use positive values to enable a limit.
• 0 or negative values are treated as disabled.
• Limit checks apply only when auth.enabled=true because limits are enforced in the auth middleware path.

Environment variable overrides

The following fields support env var overrides:

OpenTelemetry enablement with env vars:

• Any configured OTEL override enables gateway OTel instrumentation by default.
• OTEL_SDK_DISABLED=true disables gateway OTel instrumentation.

Fields not listed in this table do not have env var overrides in this release.

Example configurations

Minimal local config (SQLite, no gateway auth)

server:
  host: 0.0.0.0
  port: 8080
 
storage:
  driver: sqlite
  path: ./data/ongoingai.db
 
providers:
  openai:
    upstream: https://api.openai.com
    prefix: /openai
  anthropic:
    upstream: https://api.anthropic.com
    prefix: /anthropic
 
tracing:
  capture_bodies: false
  body_max_size: 1048576

Team mode config (Postgres, gateway auth, limits)

server:
  host: 0.0.0.0
  port: 8080
 
storage:
  driver: postgres
  dsn: POSTGRES_DSN
 
providers:
  openai:
    upstream: https://api.openai.com
    prefix: /openai
  anthropic:
    upstream: https://api.anthropic.com
    prefix: /anthropic
 
tracing:
  capture_bodies: true
  body_max_size: 262144
 
pii:
  mode: redact_storage
  policy_id: default/v1
 
auth:
  enabled: true
  header: X-OngoingAI-Gateway-Key
  keys:
    - id: dev-key-1
      token: GATEWAY_KEY_TOKEN
      org_id: org-a
      workspace_id: workspace-a
      role: developer
 
limits:
  per_key:
    requests_per_minute: 120
    max_tokens_per_day: 500000
    max_cost_usd_per_day: 25
  per_workspace:
    requests_per_minute: 600
    max_tokens_per_day: 5000000
    max_cost_usd_per_day: 250

Placeholders:

• POSTGRES_DSN: Postgres DSN, for example postgres://user:pass@db.example.com:5432/ongoingai?sslmode=require.
• GATEWAY_KEY_TOKEN: Gateway key token used in the auth header.

Validate configuration

ongoingai config validate --config ongoingai.yaml

You should see config is valid: ongoingai.yaml when validation succeeds.

Validation failures you will see

server.port must be between 1 and 65535

• Symptom: Config validation fails on startup.
• Cause: server.port is out of range.
• Fix: Set server.port to a value between 1 and 65535.

storage.path is required when storage.driver=sqlite

• Symptom: Validation fails with sqlite configuration.
• Cause: storage.path is empty while storage.driver=sqlite.
• Fix: Set storage.path to a writable file path.

storage.dsn is required when storage.driver=postgres

• Symptom: Validation fails with postgres configuration.
• Cause: storage.dsn is empty while storage.driver=postgres.
• Fix: Set a valid Postgres DSN in storage.dsn.

providers.<provider>.prefix must start with '/'

• Symptom: Validation fails for provider settings.
• Cause: Provider prefix does not start with /.
• Fix: Use values like /openai and /anthropic.

providers.<provider>.upstream must include scheme and host

• Symptom: Validation fails for provider upstream settings.
• Cause: Upstream URL is missing a scheme or host.
• Fix: Use full URLs such as https://api.openai.com.

Proxy request denied by PII guardrail policy

• Symptom: Provider route requests return 403 or 503 with a guardrail denial message.
• Cause: In redact_upstream or block, policy evaluation failed (for example oversized body, unsupported content type, or redaction evaluation error) or block mode detected protected content.
• Fix: Keep request bodies within tracing.body_max_size, use JSON/text request bodies for guarded routes, or switch to redact_storage when you need storage-only redaction.

Status semantics:

• 403: block mode detected protected content.
• 503: policy uncertainty prevented evaluation in redact_upstream or block (fail closed).

auth.header must not be empty

• Symptom: Validation fails for auth settings.
• Cause: auth.header is blank.
• Fix: Set a non-empty header name, such as X-OngoingAI-Gateway-Key.

Next steps

• Environment variable reference
• CLI reference
• Authorization reference