Skip to main content
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.

​
Two Configuration Modes

Bifrost supports two mutually exclusive modes. You cannot run both at the same time.
ModeWhenBehaviour
Web UI / databaseNo config.json, or config.json with config_store enabledFull UI available, configuration stored in SQLite or PostgreSQL
File-based (config.json)config.json present, config_store disabledUI disabled, all config loaded from file at startup, restart required for changes
See Setting Up for a full explanation of both modes and how config_store bootstrapping works.

​
Minimal Working Example

{
  "$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,
    "allow_direct_keys": false,
    "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"
    }
  }
}

​
Example Configs

Ready-to-use reference configurations from the examples/configs directory on GitHub:
ExampleDescription
noconfigstorenologstoreBare-minimum file-only mode — no database, no UI, providers loaded from file
partialSQLite config store with a minimal provider setup
v1compat"version": 1 for v1.4.x array semantics (empty = allow all)
ExampleDescription
withconfigstoreSQLite config store (Web UI enabled)
withconfigstorelogsstorepostgresPostgreSQL for both config store and logs store
withlogstoreSQLite logs store
withobjectstorages3S3 object storage offload for logs
withobjectstoragegcsGCS object storage offload for logs
withvectorstoreweaviateWeaviate vector store (with docker-compose)
ExampleDescription
withsemanticcacheSemantic cache backed by Weaviate
withsemanticcachevalkeySemantic cache backed by Valkey / Redis
ExampleDescription
withauthAdmin username/password auth (governance.auth_config)
withvirtualkeysVirtual keys with provider/model allowlists
withteamscustomersTeams and customers with budgets and rate limits
withroutingrulesCEL-based routing rules for dynamic provider/model selection
withpricingoverridesnostorePricing overrides in file-only mode
withpricingoverridessqlitePricing overrides with SQLite config store
ExampleDescription
withobservabilityPrometheus metrics (telemetry always active, custom labels via client.prometheus_labels)
withprompushgatewayPrometheus Push Gateway for multi-instance deployments
withotelOpenTelemetry traces and metrics
ExampleDescription
withdynamicpluginLoading a custom .so plugin at startup
withcompatSDK compatibility shims (should_drop_params, convert_text_to_chat)
withframeworkCustom model pricing catalog URL and sync interval
withlargepayloadLarge payload optimization (streaming without full materialisation)
withwebsocketWebSocket / Realtime API connection pool tuning
withpostgresmcpclientsinconfigMCP client definitions seeded from config.json with PostgreSQL store
encryptionmigrationMigrating 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

Governance

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

Guardrails

Content moderation providers and CEL-based rules (enterprise)

​
Next Steps

  1. Configure provider keys
  2. Enable plugins
  3. Set up observability
  4. Configure governance
  5. Deploy multiple nodes with a shared config.json