Client Configuration

The client block controls how Bifrost manages its internal worker pool, request logging, authentication enforcement, header policies, SDK compatibility shims, and MCP agent behaviour.

Connection Pool

Field	Type	Default	Description
`initial_pool_size`	integer	`300`	Pre-allocated worker goroutines per provider queue
`drop_excess_requests`	boolean	`false`	Drop requests when queue is full instead of waiting (returns HTTP 429)

A larger pool reduces latency spikes under burst load at the cost of higher baseline memory. 500–1000 is a common starting point for production workloads with multiple providers.

{
  "client": {
    "initial_pool_size": 1000,
    "drop_excess_requests": true
  }
}

Request & Response Logging

Field	Type	Default	Description
`enable_logging`	boolean	-	Log all LLM requests and responses
`disable_content_logging`	boolean	`false`	Strip message content from the Bifrost log store (keeps metadata only)
`retain_content_in_object_storage`	boolean	`false`	When content logging is disabled, offload the full content to object storage as hidden instead of dropping it. Never served back through the UI or API. Requires object storage on the logs store. See Content Logging
`allow_per_request_content_storage_override`	boolean	`false`	Allow individual requests to override content storage via the `x-bf-disable-content-logging` header or its context key, and to opt in to raw-byte persistence via `x-bf-store-raw-request-response`. When `false`, the global `disable_content_logging` setting is authoritative and per-request overrides are ignored. See Request Options
`log_retention_days`	integer	`365`	Days to retain log entries in the store
`logging_headers`	array of strings	`[]`	HTTP request headers to capture in log metadata
`hidden_request_types`	array of strings	`[]`	Request types hidden from Logs and Dashboard reads. Logs are still stored. Also editable in the UI under Logs Settings. See Hiding request types from the dashboard

Set disable_content_logging: true for HIPAA / PCI compliance workloads where message content must not be persisted, and keep retain_content_in_object_storage: false: with it on, the full payload of every content-disabled request is still persisted in the object storage bucket. A virtual key with its own disable_content_logging: false overrides this for its traffic, so audit your keys as well.

This setting does not apply to observability connectors. Each connector (BigQuery, Kafka, Pub/Sub, OpenTelemetry, Datadog) has its own disable_content_logging flag that defaults to false and is read independently of this one. Setting the client flag alone still exports full message content to every configured connector.For a compliance workload where content must not leave the deployment, set disable_content_logging: true on every configured connector as well. These flags do not cover every exported value: BigQuery writes params and tools regardless of its flag, and captured request headers are exported regardless of content flags. If those fields or headers can contain sensitive data, do not export them or apply separate controls. Keep allow_per_request_content_storage_override off, and make sure no virtual key sets disable_content_logging: false. If retain_content_in_object_storage is on, its bucket holds the full payload of every content-disabled request: turn it off when content must not be persisted, or keep the bucket inside the approved deployment boundary when retention is allowed but content must not leave the deployment. See Content Logging for how the layers compose, and for retain_content_in_object_storage, which keeps content in your storage bucket while hiding it from the UI and API.

{
  "client": {
    "enable_logging": true,
    "disable_content_logging": true,
    "log_retention_days": 90,
    "logging_headers": ["x-request-id", "x-user-id"]
  }
}

Reverse Proxy

When Bifrost acts as an OAuth client to upstream MCP servers, the redirect_uri it registers is built from the incoming Host header by default - behind a reverse proxy that is the proxy’s internal address, not its public one. One setting lets you override it with the proxy’s public URL.

Field	Type	Default	Description
`mcp_external_client_url`	string or EnvVar	-	Public base URL Bifrost uses as the `redirect_uri` against upstream MCP servers

This field supports env var syntax ("env.MY_VAR"). When unset, it falls back to the incoming Host header.

The client role

When Bifrost connects to an upstream MCP server (Notion, Jira, GitHub, etc.) on behalf of a user, it acts as an OAuth client. mcp_external_client_url is the callback Bifrost registers as its redirect_uri with those upstream providers - they redirect the user’s browser to <client URL>/api/oauth/callback after login. Set it to the proxy’s public URL so the callback resolves to a publicly reachable address.

Example

{
  "client": {
    "mcp_external_client_url": "env.BIFROST_EXTERNAL_URL"
  }
}

Or as a plain URL:

{
  "client": {
    "mcp_external_client_url": "https://oauth.yourcompany.com"
  }
}

When left empty, the redirect_uri falls back to the request’s Host header - correct for development or when no reverse proxy fronts Bifrost. This setting is also configurable via the UI (MCP Gateway → MCP Settings) and the management API, with no restart required.

Security & CORS

Field	Type	Default	Description
`allowed_origins`	array	`["*"]`	CORS allowed origins: exact URIs, wildcard-host patterns such as `https://.example.com`, or `""`. While dashboard auth is disabled, browser requests to the management API are accepted only from localhost origins, the gateway’s own origin, and origins listed here explicitly; see the note below
`enforce_auth_on_inference`	boolean	`false`	Require auth (virtual key, API key, or user token) on `/v1/*` inference routes. Realtime connections (`/v1/realtime`, `/v1/realtime/calls`) are refused with `401` at connect time unless they present one of those, or an ephemeral client secret from `POST /v1/realtime/client_secrets`
`max_request_body_size_mb`	integer	`100`	Maximum allowed request body size in MB. It also caps what a compressed request body (`Content-Encoding: gzip`, `deflate`, `br` or `zstd`) may decompress to. Within that cap a body may expand to at most 100 times its compressed size, with a 1 MiB floor, and the gateway keeps at most four times this cap of decompressed request bytes in flight at once; a body past the ratio is refused with `413`, and a request whose decompressed bytes would push the in-flight total past that budget with `503`. Each body counts what it actually inflates to, so concurrent multi-MB gzipped requests are not refused for the cap they could have reached
`dual_credential_conflict_behavior`	string	`prefer_idp`	Enterprise. What to do when an inference request carries both an IdP token (`Authorization: Bearer <jwt>`) and a virtual key. `prefer_idp` uses the IdP token’s user and drops the virtual key once the token validates, `prefer_vk` ignores the IdP token and uses the virtual key, `error` rejects the request with `400`
`whitelisted_routes`	array of strings	`[]`	Routes that bypass auth middleware
`allowed_headers`	array of strings	`[]`	Additional headers permitted for CORS and WebSocket
`allow_direct_keys`	boolean	`false`	Allow callers to bypass the registered key pool by sending `x-bf-direct-key: true` and a raw provider key in `Authorization` / `x-api-key` / `x-goog-api-key`. See Direct API Key
`delete_expired_virtual_keys`	boolean	`false`	Delete expired virtual keys with a daily cleanup job. A key can override this with its own `delete_after_expire`. See Virtual key expiry

{
  "client": {
    "allowed_origins": [
      "https://app.yourcompany.com",
      "https://admin.yourcompany.com"
    ],
    "enforce_auth_on_inference": true,
    "max_request_body_size_mb": 50,
    "whitelisted_routes": ["/health", "/metrics"]
  }
}

While dashboard auth is disabled or unconfigured, or Bifrost runs without a config store (config_store.enabled: false), a request to the management API (/api/*, /ws, /metrics) that carries an Origin header is accepted only from a localhost origin, from the gateway’s own origin (the Origin host and port match the request’s Host, as for the bundled dashboard’s own requests such as PUT /api/config), or from an origin listed in allowed_origins by name or pattern (for example https://*.example.com); the "*" entry does not count, and other origins receive 403. Requests without an Origin header (CLI and SDKs), whitelisted routes such as /health, and inference routes are unaffected. If the dashboard sits behind a proxy that rewrites the Host header, list its public origin in allowed_origins. To call the management API from a web app on another origin, list that origin explicitly, or enable dashboard authentication, which lifts this check. Dashboard authentication needs the config store: with config_store.enabled: false it cannot be turned on, so listing the origin is the only option.

Header Filtering

Controls which x-bf-eh-* extra headers are forwarded to upstream LLM providers.

Field	Type	Default	Description
`header_filter_config.allowlist`	array of strings	`[]`	Only these headers are forwarded (whitelist mode)
`header_filter_config.denylist`	array of strings	`[]`	These headers are always blocked
`required_headers`	array of strings	`[]`	Headers that must be present on every request (rejected with 400 if missing)

When both allowlist and denylist are empty, all x-bf-eh-* headers pass through. Specifying an allowlist enables strict whitelist mode - only listed headers are forwarded.

{
  "client": {
    "header_filter_config": {
      "allowlist": [
        "x-bf-eh-anthropic-version",
        "x-bf-eh-openai-beta"
      ],
      "denylist": []
    },
    "required_headers": ["x-request-id"]
  }
}

Compat Shims

Compatibility flags that let Bifrost silently adapt request/response shapes for SDK integrations.

Field	Type	Default	Description
`compat.convert_text_to_chat`	boolean	`false`	Wrap legacy `/v1/completions` text requests as chat messages
`compat.convert_chat_to_responses`	boolean	`false`	Translate chat completions to Responses API format
`compat.should_drop_params`	boolean	`false`	Silently drop unsupported parameters instead of erroring
`compat.should_convert_params`	boolean	`false`	Auto-convert parameter values across provider schemas
`compat.azure_deepseek`	boolean	`false`	Convert Azure DeepSeek responses requests to chat completions so reasoning is preserved for coding harnesses
`compat.force_reasoning_only_models_to_responses`	boolean	`true`	Convert chat completion requests to Responses for models whose datasheet sets `supports_reasoning_with_tool_calls: false`, so reasoning is kept instead of forced off
`compat.convert_decision_to_responses`	boolean	`false`	Answer decision requests for models without a native decisions endpoint through the Responses API. See Decision-to-Responses Emulation

{
  "client": {
    "compat": {
      "should_drop_params": true,
      "convert_text_to_chat": true
    }
  }
}

Agent Gateway and Skills Marketplace URLs

Configure these public base URLs independently. Neither feature derives its public URL from request headers. Public base URLs for MCP, Agent Gateway, and Skills must use HTTP or HTTPS and must not contain userinfo, query strings, or fragments. Ports and path prefixes are supported. API updates reject invalid URLs without echoing their values. Config loading ignores invalid overrides: Agent Gateway and skills marketplace serving stay disabled, while MCP retains its request-derived callback fallback.

Field	Type	Default	Description
`a2a_external_client_url`	string or secret reference	Unset	Enables Agent Gateway protocol operations and supplies agent-card and push-callback URLs.
`skills_external_client_url`	string or secret reference	Unset	Enables Skills Repository marketplace registration and serving. Git must also be installed on the server.

{
  "client": {
    "a2a_external_client_url": "https://bifrost.example.com",
    "skills_external_client_url": "https://bifrost.example.com"
  }
}

Both fields support environment references such as env.BIFROST_EXTERNAL_URL and vault references. They may share a value, but there is no common base-URL setting. Without a resolved Agent Gateway URL, HTTP protocol endpoints return 503 and A2A gRPC operations return UNAVAILABLE. Agent registration and management remain available. Without a resolved skills URL, marketplace registration and serving are disabled; skill management and direct downloads remain available. Use Agents → Agent Settings or Skills → Skills Settings to update the corresponding URL in the dashboard. See Agent Gateway configuration and Skills Repository marketplace access.

MCP Agent Settings

Field	Type	Default	Description
`mcp_agent_depth`	integer	`10`	Maximum tool-call recursion depth for MCP agent mode
`mcp_tool_execution_timeout`	integer	`30`	Timeout per MCP tool execution in seconds
`mcp_code_mode_binding_level`	string	-	Code mode binding level: `"server"` or `"tool"`
`mcp_tool_sync_interval`	integer	`10`	Global tool sync interval in minutes (`0` = default of 10 minutes)
`mcp_disable_auto_tool_inject`	boolean	`false`	When `true`, MCP tools are not automatically injected into requests

{
  "client": {
    "mcp_agent_depth": 15,
    "mcp_tool_execution_timeout": 60,
    "mcp_tool_sync_interval": 10
  }
}

Async Jobs

Field	Type	Default	Description
`async_job_result_ttl`	integer	`3600`	TTL (seconds) for async job results
`disable_db_pings_in_health`	boolean	`false`	Exclude database connectivity from `/health` endpoint checks

Prometheus Labels

Add custom labels to every Prometheus metric emitted by Bifrost:

{
  "client": {
    "prometheus_labels": ["environment=production", "region=us-east-1"]
  }
}

Authentication

governance.auth_config protects the Bifrost dashboard and management API with username/password auth.

Field	Type	Default	Description
`is_enabled`	boolean	`false`	Enable username/password auth
`admin_username`	string	-	Admin username
`admin_password`	string	-	Admin password (use `env.` reference)
`disable_auth_on_inference`	boolean	`false`	Skip auth check on `/v1/*` inference routes

{
  "governance": {
    "auth_config": {
      "is_enabled": true,
      "admin_username": "env.BIFROST_ADMIN_USERNAME",
      "admin_password": "env.BIFROST_ADMIN_PASSWORD",
      "disable_auth_on_inference": false
    }
  }
}

A top-level auth_config is also accepted for backwards compatibility, but governance.auth_config is the preferred location.

Encryption Key

{
  "encryption_key": "env.BIFROST_ENCRYPTION_KEY"
}

Notes
Accepts any string; Bifrost derives a 32-byte AES-256 key using Argon2id
Can also be set via the `BIFROST_ENCRYPTION_KEY` environment variable
Once set and the database is populated, the key cannot be changed without clearing the database
Omitting the key stores data in plain text - not recommended for production

Global Proxy

The global outbound proxy is the one on the dashboard’s Config → Proxy page, including which components send their outbound requests through it. Declare it as a top-level proxy_config (not to be confused with a provider’s own proxy_config):

{
  "proxy_config": {
    "enabled": true,
    "type": "http",
    "url": "http://proxy.example.com:8080",
    "username": "env.PROXY_USERNAME",
    "password": "env.PROXY_PASSWORD",
    "no_proxy": "localhost,.internal.example.com",
    "timeout": 30,
    "enable_for_scim": true,
    "enable_for_inference": false,
    "enable_for_api": false
  }
}

Field	Default	Description
`enabled`	`false`	Turn the proxy on
`type`	`"http"`	Proxy type. Only `http` is supported
`url`	-	Proxy URL. Required when `enabled` is `true`. Supports `env.VAR_NAME`
`username` / `password`	-	Optional proxy credentials. Support `env.VAR_NAME`
`no_proxy`	-	Comma-separated hosts that bypass the proxy: exact hosts, `.example.com` (domain and subdomains), `.example.com` (subdomains only), or ``
`timeout`	`0`	Connection timeout in seconds
`skip_tls_verify`	`false`	Skip TLS verification for the proxy
`enable_for_scim`	`false`	(enterprise) Route SCIM directory sync and identity-provider requests through the proxy
`enable_for_inference`	`false`	Route inference requests through the proxy
`enable_for_api`	`false`	Route API requests through the proxy

Full Example

{
  "$schema": "https://www.getbifrost.ai/schema",
  "encryption_key": "env.BIFROST_ENCRYPTION_KEY",

  "governance": {
    "auth_config": {
      "is_enabled": true,
      "admin_username": "env.BIFROST_ADMIN_USERNAME",
      "admin_password": "env.BIFROST_ADMIN_PASSWORD",
      "disable_auth_on_inference": false
    }
  },

  "client": {
    "initial_pool_size": 1000,
    "drop_excess_requests": true,

    "enable_logging": true,
    "disable_content_logging": false,
    "log_retention_days": 90,
    "logging_headers": ["x-request-id", "x-user-id"],

    "mcp_external_client_url": "env.BIFROST_EXTERNAL_URL",

    "allowed_origins": ["https://app.yourcompany.com"],
    "enforce_auth_on_inference": true,
    "max_request_body_size_mb": 100,

    "header_filter_config": {
      "allowlist": [],
      "denylist": []
    },
    "required_headers": [],

    "compat": {
      "should_drop_params": false
    },

    "prometheus_labels": ["environment=production"],

    "mcp_agent_depth": 10,
    "mcp_tool_execution_timeout": 30,

    "async_job_result_ttl": 3600
  }
}

Managed Kubernetes

Hosted Containers

Config as Code

Enterprise Deployment

Common setup instructions

Client Configuration

Connection Pool

Request & Response Logging

Reverse Proxy

The client role

Example

Security & CORS

Header Filtering

Compat Shims

Agent Gateway and Skills Marketplace URLs

MCP Agent Settings

Async Jobs

Prometheus Labels

Authentication

Encryption Key

Global Proxy

Full Example

​Connection Pool

​Request & Response Logging

​Reverse Proxy

​The client role

​Example

​Security & CORS

​Header Filtering

​Compat Shims

​Agent Gateway and Skills Marketplace URLs

​MCP Agent Settings

​Async Jobs

​Prometheus Labels

​Authentication

​Encryption Key

​Global Proxy

​Full Example

Connection Pool

Request & Response Logging

Reverse Proxy

The client role

Example

Security & CORS

Header Filtering

Compat Shims

Agent Gateway and Skills Marketplace URLs

MCP Agent Settings

Async Jobs

Prometheus Labels

Authentication

Encryption Key

Global Proxy

Full Example