Schema Reference

All top-level keys available in config.json, their types, and where each is documented

The live schema is published at https://www.getbifrost.ai/schema. Add "$schema": "https://www.getbifrost.ai/schema" to your config.json for IDE autocomplete and inline validation, or point it to a mirrored HTTP(S) URL, file:// URL, or filesystem path in isolated deployments. You can also set the BIFROST_SCHEMA_URL environment variable, which takes precedence over the $schema value. When mirroring, snapshot a schema published by a Bifrost release that supports custom $schema values; older schema copies pin $schema to the public URL and will flag a mirrored location as invalid in IDEs.

This page is a concise reference for every top-level key in config.json. Click the Guide links for full field-by-field documentation.

---

Top-Level Keys

Key	Type	Description	Guide
$schema	string	Schema location for IDE validation. Defaults to "https://www.getbifrost.ai/schema"; isolated deployments can use a mirrored URL, file:// URL, or filesystem path.	-
version	integer	Compatibility switch for empty allow-list arrays. Omit for current v2 semantics.	version
source_of_truth	string	Startup reconciliation mode for DB-backed config.json: "split" or "config.json"	Source of Truth
encryption_key	string	Optional AES-256 key (derived via Argon2id). Accepts env.VAR prefix and is also read from BIFROST_ENCRYPTION_KEY. If omitted, data is stored in plaintext.	Client
client	object	Worker pool, logging, CORS, auth enforcement, header filtering, MCP, compat shims	Client
providers	object	LLM provider API keys, network settings, concurrency	Providers
governance	object	Admin auth, virtual keys, budgets, rate limits, routing rules, customers, teams	Governance
alerting	object	Alert channels, CEL-based rules, history retention, and webhook network controls (enterprise only)	Alerting
guardrails_config	object	Content moderation providers and CEL-based rules (enterprise only)	Guardrails
access_profiles	array	Access profile templates for enterprise RBAC/governance controls (enterprise only)	Enterprise Governance
cluster_config	object	Cluster mode settings: gossip, peers, and auto-discovery backends (enterprise only)	Cluster
config_store	object	Configuration database backend - SQLite, PostgreSQL, or disabled (file-only mode)	Storage
logs_store	object	Request/response log database - SQLite, PostgreSQL + optional S3/GCS offload	Storage
vector_store	object	Vector database for semantic cache - Weaviate, Redis, Qdrant, Pinecone, Valkey	Storage
plugins	array	Opt-in plugins: semantic_cache, otel, maxim, datadog, custom	Plugins
framework	object	Model pricing catalog URL and sync interval	Framework
mcp	object	MCP server and tool configuration	MCP
websocket	object	WebSocket / Realtime API connection pool tuning	WebSocket
auth_config	object	Deprecated - use governance.auth_config	Client

---

version

Controls how empty arrays in allow-list fields (models, allowed_models, key_ids, tools_to_execute) are interpreted:

Value	Behaviour
2 (default, v1.5.0+)	Empty array = deny all; ["*"] = allow all
1 (v1.4.x compat)	Empty array = allow all

Omitting version uses v2 semantics. Set "version": 1 only if you are migrating from v1.4.x and need the old behaviour temporarily.

---

source_of_truth

Controls how config.json is reconciled with the config store at startup.

Value	Behaviour
"split" (default)	File-backed rows seed or update the config store by hash, while unchanged file-backed rows preserve UI/API edits
"config.json"	Explicitly present file sections are authoritative and replace matching DB state on startup

Missing and empty sections behave differently when source_of_truth is "config.json". A missing section leaves DB rows untouched; a present empty section is authoritative and can prune matching DB rows.

{
  "source_of_truth": "config.json",
  "plugins": []
}

The example above makes the plugins section present and empty, so stored plugins are removed on startup. See Source of Truth & Reconciliation for section-by-section behavior.

---

client

Controls the worker pool, logging pipeline, security, and SDK shims. All fields are optional.

Field	Type	Default	Description
initial_pool_size	integer	300	Pre-allocated goroutines per provider queue
drop_excess_requests	boolean	false	Return HTTP 429 when queue is full
enable_logging	boolean	true*	Persist request/response logs (* auto-enabled when logs_store is set)
disable_content_logging	boolean	false	Strip message content from logs
log_retention_days	integer	365	Days to retain log entries
logging_headers	array	[]	HTTP headers to capture in log metadata
enforce_auth_on_inference	boolean	false	Require a virtual key on every /v1/* request
allowed_origins	array	["*"]	CORS allowed origins
allow_direct_keys	boolean	false	Let callers bypass the key pool with x-bf-direct-key: true + a raw provider key
max_request_body_size_mb	integer	100	Maximum request body in MB
whitelisted_routes	array	[]	Routes that bypass auth middleware
allowed_headers	array	[]	Additional headers permitted for CORS/WebSocket
required_headers	array	[]	Headers that must be present on every request
header_filter_config	object	-	allowlist / denylist for x-bf-eh-* forwarded headers
prometheus_labels	array	[]	Custom labels for all Prometheus metrics
compat	object	-	SDK compatibility shims (should_drop_params, convert_text_to_chat, etc.)
mcp_agent_depth	integer	10	Max tool-call recursion depth
mcp_tool_execution_timeout	integer or string	30	Per-tool execution timeout in seconds (integer = seconds, string = Go duration like ”30s”, “2m”)
mcp_tool_sync_interval	integer	10	Tool sync interval in minutes (0 = default of 10 minutes)
mcp_disable_auto_tool_inject	boolean	false	Disable automatic MCP tool injection
async_job_result_ttl	integer	3600	TTL for async job results in seconds
disable_db_pings_in_health	boolean	false	Exclude DB connectivity from /health
routing_chain_max_depth	integer	10	Max routing rule chain evaluation depth
mcp_external_client_url	string | EnvVar	-	Public base URL used as redirect_uri against upstream MCP OAuth providers; supports "env.MY_VAR"

Full documentation: Client Configuration.

---

providers

Keyed by provider name. Each entry contains a keys array and optional network_config, concurrency_and_buffer_size, proxy_config.

Supported provider keys: openai, anthropic, azure, bedrock, vertex, gemini, mistral, groq, cohere, perplexity, xai, cerebras, deepseek, openrouter, nebius, fireworks, parasail, huggingface, replicate, ollama, vllm, sgl, elevenlabs, runway.

Full documentation: Provider Setup.

---

governance

Seeds governance resources at startup. All sub-keys are optional arrays.

Sub-key	Description
auth_config	Admin username/password auth for the dashboard
virtual_keys	Scoped API tokens with provider/model allowlists
budgets	Spend caps in USD over a rolling window
rate_limits	Request and token rate limits
customers	Customer entities (attach budgets/rate limits)
teams	Team entities (attach to customers and rate limits; budgets attach to teams through budgets[].team_id)
routing_rules	CEL-based dynamic provider/model routing
pricing_overrides	Scoped per-model pricing overrides
model_configs	Per-model rate limit and budget configurations

Full documentation: Governance.

---

guardrails_config

Enterprise-only. Two sub-keys: guardrail_providers (array) and guardrail_rules (array).

Full documentation: Guardrails.

---

alerting

Enterprise-only. Supports channels (array), rules (array), history_retention_days, evaluation_interval_seconds, and webhook_network.

Full documentation: Alerting.

---

access_profiles

Enterprise-only. Defines access profile templates that can later be attached to roles/users.

{
  "access_profiles": [
    {
      "name": "platform-default",
      "description": "Default platform profile",
      "is_active": true,
      "tags": ["platform", "default"],
      "provider_configs": [
        {
          "provider_name": "openai",
          "all_models_allowed": false,
          "allowed_models": ["gpt-4o", "gpt-4o-mini"]
        }
      ],
      "mcp_servers": [
        { "mcp_server_id": "github" }
      ],
      "mcp_tool_overrides": [
        { "mcp_client_id": "github", "tool_name": "create_pull_request", "action": "include" }
      ]
    }
  ]
}

---

cluster_config

Enterprise-only clustering settings for multi-node deployments.

Sub-key	Description
enabled	Enables cluster mode
region	Region label used by enterprise clustering
peers	Static peer list (host:port)
gossip	Gossip/memberlist port + liveness thresholds
discovery	Auto-discovery configuration (kubernetes, dns, udp, consul, etcd, mdns)

Full documentation: Cluster.

---

config_store, logs_store, vector_store

Storage backends. Each has enabled (boolean), type (string), and config (object).

Store	Types
config_store	"sqlite", "postgres"
logs_store	"sqlite", "postgres" (+ optional object_storage for LLM and MCP logs)
vector_store	"weaviate", "redis", "qdrant", "pinecone" ("redis" also covers Valkey-compatible endpoints)

Full documentation: Storage.

---

framework

Controls model pricing catalog sync and background model discovery:

{
  "framework": {
    "pricing": {
      "pricing_url": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json",
      "pricing_sync_interval": 86400,
      "live_models_sync_interval": 3600
    }
  }
}

Field	Default	Description
pricing.pricing_url	LiteLLM catalog	URL of a model pricing JSON file
pricing.pricing_sync_interval	86400	Sync interval in seconds (minimum: 3600)
pricing.live_models_sync_interval	3600	How often each provider’s model list is re-fetched, in seconds. 0 disables it (minimum when enabled: 60)

Background model discovery

Each provider’s model list is fetched at startup and whenever you add, edit, or delete a key. live_models_sync_interval additionally re-fetches it on a timer, so a model a provider starts serving after the gateway booted becomes routable without a restart.

Every node runs its own refresh, because the model list is cached in process memory rather than in the database. Each pass costs two list models calls per enabled key, per provider, so raise the interval if a provider meters that endpoint. The interval is jittered by ±10% to keep replicas that booted together from calling every upstream at the same instant.

Set it to 0 to turn the timer off entirely. Model discovery then happens only at startup and on key edits, and you can trigger it on demand from the Providers page.

---

mcp

Declares the catalog of MCP servers Bifrost connects to. Each entry in client_configs is one MCP server.

{
  "mcp": {
    "client_configs": [
      {
        "name": "weather",
        "connection_type": "http",
        "connection_string": "https://mcp.example.com/weather",
        "auth_type": "none",
        "tools_to_execute": ["*"]
      }
    ]
  }
}

Common fields on each client_configs entry:

Field	Type	Description
name	string	Unique display name
client_id	string	Optional stable client identifier (defaults to a generated UUID)
connection_type	string	"http", "sse", or "stdio"
connection_string	object/string	HTTP/SSE URL or stdio command spec
auth_type	string	"none", "headers", "oauth", "per_user_oauth", "per_user_headers", or "token_exchange" (enterprise only — see below)
tools_to_execute	array	Allow-list of tool names; ["*"] for all
tools_to_auto_execute	array	Subset of tools_to_execute that runs without user confirmation
headers	object	Static admin headers (used by headers and as additions on per_user_headers)
is_code_mode_client	boolean	Wrap tools as Python code-mode helpers instead of raw tool calls
needs_session_stickiness	boolean	HTTP-only, and only meaningful for oauth/headers/none (per-user auth types are always per-call). true holds one persistent upstream connection reused for every tool call; false/omitted (default) dials fresh per tool call. Cannot be false for connection_type "sse"/"stdio" — both are always sticky. See Session Stickiness.
is_ping_available	boolean	Default true. Whether the MCP server supports a lightweight ping for health checks; false falls back to a full listTools call instead.
tool_sync_interval	string | integer	Per-client tool-list sync interval as a Go duration string in whole seconds (for example "5m" or "90s"), or a legacy non-negative integer in nanoseconds that is a whole number of seconds. "0s"/omitted falls back to the global mcp.tool_sync_interval.
tool_execution_timeout	integer	Per-client tool execution timeout in seconds. 0/omitted falls back to the global client.mcp_tool_execution_timeout.
allow_on_all_virtual_keys	boolean	When true, every virtual key can use this client without an explicit allowlist entry.
tls_config	object	{ "insecure_skip_verify": bool, "ca_cert_pem": string } — skip TLS verification (development only) and/or trust a custom CA certificate for this client’s connection. ca_cert_pem supports env.VAR_NAME.

Auth-type-specific fields:

Field	Auth type	Description
oauth_config	oauth, per_user_oauth	Optional inline OAuth provider block. The whole block can be omitted, and any inner field (client_id, client_secret, authorize_url, token_url, registration_url, scopes) can be omitted individually — RFC 8414 metadata discovery + RFC 7591 dynamic client registration fill the gaps off connection_string at admin-click time. client_id / client_secret support env.VAR_NAME and vault.path references (resolved at runtime, reference stored); the other fields take literal values (encrypted at rest, redacted in API responses).
per_user_header_keys	per_user_headers	Required, non-empty. Array of header names each end-user must supply.
token_exchange	token_exchange	Required. { "audience": string, "use_idp_credentials": boolean (optional, default false), "client_id": SecretVar (required unless use_idp_credentials is true), "client_secret": SecretVar (optional, public clients; ignored when use_idp_credentials is true), "scopes": string[] (optional), "authorization_server_url": string (optional) }. client_id/client_secret support env.VAR_NAME/vault.path references. use_idp_credentials performs the exchange as the SSO login application instead of a dedicated one — required for Microsoft Entra ID, see Token Exchange auth. Include "offline_access" in scopes where the identity provider supports it to keep the retained admin discovery credential self-renewing instead of expiring into needs_reauth.

The schema enforces these pairings: oauth_config is rejected on non-OAuth auth types, per_user_header_keys is rejected on any auth type other than per_user_headers, and token_exchange is rejected on any auth type other than token_exchange — a misplaced block fails $schema validation instead of being silently ignored.

Enterprise only: auth_type: "token_exchange" in config.json is rejected on OSS — the client is skipped entirely at boot with an error logged naming it. Declare token_exchange clients via the API/Web UI on an enterprise deployment instead if you need them in a non-enterprise config.json environment during a migration.

Migration note: oauth_config_id is no longer a valid field on MCP client entries in config.json. Older guidance for shared OAuth suggested checking it in after completing an OAuth flow — remove it from existing config files (declare an oauth_config block instead, or leave the client to the dashboard). Bifrost now ignores the field if present (with a warning at boot): the OAuth link is managed server-side and survives restarts and config re-syncs on its own, and $schema-based editor/CI validation rejects the field.

Clients declared with auth_type in {oauth, per_user_oauth, per_user_headers, token_exchange} boot into a pending_verification state. The MCP Gateway UI surfaces an Authorize / Verify CTA on each pending row; one admin click runs the same verification flow the Web UI Create form uses, after which the client transitions to healthy. The same steps are scriptable via POST /api/mcp/client/{id}/initiate-verification (OAuth types), POST /api/mcp/client/{id}/verify-headers (per-user headers), or POST /api/mcp/client/{id}/verify-exchange (token exchange). Verified state is server-side and survives restarts and config re-syncs. Immutable fields (auth_type, connection_type, connection_string, stdio_config, oauth_config) cannot be changed after creation — file edits to them are ignored with a boot warning naming the fields, matching the update API; delete and re-declare the client to change them. See MCP Auth and Connections, States & Lifecycles.

---

websocket

Optional tuning for the WebSocket gateway (Responses API WebSocket mode, Realtime API). WebSocket is always enabled.

{
  "websocket": {
    "max_connections_per_user": 100,
    "transcript_buffer_size": 100,
    "pool": {
      "max_idle_per_key": 50,
      "max_total_connections": 1000,
      "idle_timeout_seconds": 600,
      "max_connection_lifetime_seconds": 7200
    }
  }
}

Field	Default	Description
max_connections_per_user	100	Max concurrent WebSocket connections per user
transcript_buffer_size	100	Transcript entries buffered for Realtime API mid-session fallback
pool.max_idle_per_key	50	Max idle upstream connections per provider/key
pool.max_total_connections	1000	Max total idle upstream connections
pool.idle_timeout_seconds	600	Evict idle connections after this many seconds
pool.max_connection_lifetime_seconds	7200	Max lifetime of any upstream connection

---

Minimal Valid Config

{
  "$schema": "https://www.getbifrost.ai/schema",
  "encryption_key": "env.BIFROST_ENCRYPTION_KEY",
  "providers": {
    "openai": {
      "keys": [
        { "name": "primary", "value": "env.OPENAI_API_KEY", "models": ["*"], "weight": 1.0 }
      ]
    }
  },
  "config_store": { "enabled": false }
}