Schema Reference

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	-
`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` = disabled)
`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, budgets, rate limits)
`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:

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

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`)

`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 }
}

Platform specific guides

Config as Code

Enterprise Deployment

Common setup instructions

Schema Reference

Top-Level Keys

`version`

`source_of_truth`

`client`

`providers`

`governance`

`guardrails_config`

`alerting`

`access_profiles`

`cluster_config`

`config_store`, `logs_store`, `vector_store`

`framework`

`websocket`

Minimal Valid Config

​Top-Level Keys

​version

​source_of_truth

​client

​providers

​governance

​guardrails_config

​alerting

​access_profiles

​cluster_config

​config_store, logs_store, vector_store

​framework

​websocket

​Minimal Valid Config

Top-Level Keys

`version`

`source_of_truth`

`client`

`providers`

`governance`

`guardrails_config`

`alerting`

`access_profiles`

`cluster_config`

`config_store`, `logs_store`, `vector_store`

`framework`

`websocket`

Minimal Valid Config