Quick Start - Bifrost

Full schema reference: https://www.getbifrost.ai/schema

config.json lets you configure every aspect of Bifrost through a single declarative file. It is the right choice for GitOps workflows, CI/CD pipelines, headless deployments, and multinode OSS setups where a central configuration file is shared across all replicas.

Configuration Sources

Bifrost stores runtime configuration in a config database by default, so settings can be edited through the Web UI or API. You can also provide a config.json file to seed or reconcile that database at startup. To run with only config.json, set config_store.enabled: false.

Setup	When	Behaviour
Web UI / database	No `config.json`	Bifrost creates a default SQLite config store and runtime changes are saved through the UI or API
DB-backed `config.json`	`config.json` exists and `config_store` is omitted or enabled	File-backed sections seed or reconcile the config store at startup; UI/API edits remain available
File-only `config.json`	`config_store.enabled` is `false`	Config is loaded from file into memory at startup; config-backed UI/API changes are unavailable and file changes require restart

By default, DB-backed config.json uses source_of_truth: "split": unchanged file-backed rows preserve UI/API edits, while changed file-backed rows are applied on the next startup. Use source_of_truth: "config.json" only when explicitly present file sections should replace matching DB state. See Source of Truth & Reconciliation for the full rules, including missing-vs-empty section behavior.

Minimal Working Example

This example uses file-only configuration for the smallest self-contained setup.

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

Save this as config.json in your app directory and start Bifrost:

# NPX
npx -y @maximhq/bifrost -app-dir ./data

# Docker
docker run -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  -e OPENAI_API_KEY=sk-... \
  -e BIFROST_ENCRYPTION_KEY=your-32-byte-key \
  maximhq/bifrost

Make your first call:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Environment Variable References

Never put secrets directly in config.json. Use the env. prefix to reference any environment variable:

{
  "encryption_key": "env.BIFROST_ENCRYPTION_KEY",
  "providers": {
    "openai": {
      "keys": [
        {
          "name": "primary",
          "value": "env.OPENAI_API_KEY",
          "weight": 1.0
        }
      ]
    }
  }
}

Set the actual values through your deployment platform - shell environment, Docker -e, Kubernetes Secrets mounted as env vars, or a .env file.

Schema Validation

Add $schema to every config.json for IDE autocomplete and inline validation:

{
  "$schema": "https://www.getbifrost.ai/schema"
}

Editors (VS Code, JetBrains, Neovim with LSP) will show completions and flag invalid fields as you type.

Production Example

A production-ready file with PostgreSQL storage, multi-provider setup, governance, and common plugins:

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

  "client": {
    "initial_pool_size": 500,
    "drop_excess_requests": true,
    "enable_logging": true,
    "log_retention_days": 90,
    "enforce_auth_on_inference": true,
    "allowed_origins": ["https://app.yourcompany.com"]
  },

  "providers": {
    "openai": {
      "keys": [
        {
          "name": "openai-primary",
          "value": "env.OPENAI_API_KEY",
          "models": ["*"],
          "weight": 1.0
        }
      ],
      "network_config": {
        "default_request_timeout_in_seconds": 120,
        "max_retries": 3
      }
    },
    "anthropic": {
      "keys": [
        {
          "name": "anthropic-primary",
          "value": "env.ANTHROPIC_API_KEY",
          "models": ["*"],
          "weight": 1.0
        }
      ]
    }
  },

  "config_store": {
    "enabled": true,
    "type": "postgres",
    "config": {
      "host": "env.PG_HOST",
      "port": "5432",
      "user": "env.PG_USER",
      "password": "env.PG_PASSWORD",
      "db_name": "bifrost",
      "ssl_mode": "require"
    }
  },

  "logs_store": {
    "enabled": true,
    "type": "postgres",
    "config": {
      "host": "env.PG_HOST",
      "port": "5432",
      "user": "env.PG_USER",
      "password": "env.PG_PASSWORD",
      "db_name": "bifrost",
      "ssl_mode": "require"
    }
  }
}

Enterprise Example: Postgres + etcd + Access Profiles

Use this pattern when you want enterprise access-profile configuration to be seeded directly from config.json, while running clustered nodes with etcd discovery.

{
  "$schema": "https://www.getbifrost.ai/schema",
  "cluster_config": {
    "enabled": true,
    "discovery": {
      "enabled": true,
      "type": "etcd",
      "service_name": "bifrost-cluster",
      "etcd_endpoints": ["http://localhost:2379"]
    }
  },
  "config_store": {
    "enabled": true,
    "type": "postgres",
    "config": {
      "host": "localhost",
      "port": "5432",
      "user": "postgres",
      "password": "env.PG_PASSWORD",
      "db_name": "bifrost-config",
      "ssl_mode": "disable"
    }
  },
  "logs_store": {
    "enabled": true,
    "type": "postgres",
    "config": {
      "host": "localhost",
      "port": "5432",
      "user": "postgres",
      "password": "env.PG_PASSWORD",
      "db_name": "bifrost-config",
      "ssl_mode": "disable"
    }
  },
  "mcp": {
    "client_configs": [
      {
        "client_id": "echo_http",
        "name": "echo_http",
        "connection_type": "http",
        "connection_string": "https://mcpplaygroundonline.com/mcp-echo-server",
        "auth_type": "none",
        "tools_to_execute": ["echo"]
      }
    ]
  },
  "access_profiles": [
    {
      "name": "platform-default",
      "description": "Default profile for enterprise access-profile testing",
      "is_active": true,
      "tags": ["platform", "test"],
      "provider_configs": [
        {
          "provider_name": "OpenAi",
          "all_models_allowed": false,
          "allowed_models": ["gpt-4o-mini"]
        }
      ]
    },
    {
      "name": "platform-readonly-mcp",
      "description": "Profile for validating MCP include/exclude behavior",
      "is_active": true,
      "tags": ["mcp", "test"],
      "mcp_servers": [
        {
          "mcp_server_id": "echo_http"
        }
      ],
      "mcp_tool_overrides": [
        {
          "mcp_client_id": "echo_http",
          "tool_name": "echo",
          "action": "include"
        },
        {
          "mcp_client_id": "github",
          "tool_name": "create_pull_request",
          "action": "exclude"
        }
      ]
    }
  ]
}

access_profiles is an enterprise capability. For OSS-only deployments, use governance.virtual_keys and related governance resources instead.

Example Configs

Ready-to-use reference configurations from the examples/configs directory on GitHub:

Minimal / File-only

Example	Description
noconfigstorenologstore	Bare-minimum file-only mode - no database, no UI, providers loaded from file
partial	SQLite config store with a minimal provider setup
v1compat	`"version": 1` for v1.4.x array semantics (empty = allow all)

Storage

Example	Description
withconfigstore	SQLite config store (Web UI enabled)
withconfigstorelogsstorepostgres	PostgreSQL for both config store and logs store
withlogstore	SQLite logs store
withobjectstorages3	S3 object storage offload for logs
withobjectstoragegcs	GCS object storage offload for logs
withvectorstoreweaviate	Weaviate vector store (with docker-compose)

Semantic Cache

Example	Description
withsemanticcache	Semantic cache backed by Weaviate
withsemanticcachevalkey	Semantic cache backed by Valkey / Redis

Governance

Example	Description
withauth	Admin username/password auth (`governance.auth_config`)
withvirtualkeys	Virtual keys with provider/model allowlists
withteamscustomers	Teams and customers with budgets and rate limits
withroutingrules	CEL-based routing rules for dynamic provider/model selection
withpricingoverridesnostore	Pricing overrides in file-only mode
withpricingoverridessqlite	Pricing overrides with SQLite config store

Observability

Example	Description
withobservability	Prometheus metrics (telemetry always active, custom labels via `client.prometheus_labels`)
withprompushgateway	Prometheus Push Gateway for multi-instance deployments
withotel	OpenTelemetry traces and metrics

Plugins & Advanced

Example	Description
withdynamicplugin	Loading a custom `.so` plugin at startup
withcompat	SDK compatibility shims (`should_drop_params`, `convert_text_to_chat`)
withframework	Custom model pricing catalog URL and sync interval
withlargepayload	Large payload optimization (streaming without full materialisation)
withwebsocket	WebSocket / Realtime API connection pool tuning
withnginxreverseproxy	3-node Bifrost behind NGINX reverse proxy (includes docker-compose, nginx.conf, helm values, and k8s ingress)
withpostgresmcpclientsinconfig	MCP client definitions seeded from config.json with PostgreSQL store
encryptionmigration	Migrating to a new encryption key

Configuration Guides

Schema Reference

Every top-level key, its type, default, and where it is documented

Client Configuration

Pool size, logging, CORS, header filtering, compat shims, MCP settings

Provider Setup

OpenAI, Anthropic, Azure, Bedrock, Vertex, Groq, self-hosted

Storage

config_store, logs_store, vector_store - SQLite, PostgreSQL, object storage

Plugins

Semantic cache, OTel, Maxim, Datadog, custom plugins

Cluster

Cluster mode with static peers or discovery backends (enterprise)

Governance

Virtual keys, budgets, rate limits, routing rules, admin auth

Guardrails

Content moderation providers and CEL-based rules (enterprise)

Next Steps

Configure provider keys
Enable plugins
Set up observability
Configure governance
Deploy multiple nodes with a shared config.json

​Configuration Sources

​Minimal Working Example

​Environment Variable References

​Schema Validation

​Production Example

​Enterprise Example: Postgres + etcd + Access Profiles

​Example Configs

​Configuration Guides

Schema Reference

Client Configuration

Provider Setup

Storage

Plugins

Cluster

Governance

Guardrails

​Next Steps

Configuration Sources

Minimal Working Example

Environment Variable References

Schema Validation

Production Example

Enterprise Example: Postgres + etcd + Access Profiles

Example Configs

Configuration Guides

Next Steps