beyhan/bifrost
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Beyhan Oğur
2026-04-26 21:52:23 +03:00
commit 880f412e2c
2662 changed files with 866266 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

416
docs/deployment-guides/config-json.mdx Normal file
View File

@@ -0,0 +1,416 @@
---
title: "Quick Start"
description: "Configure Bifrost using a config.json file — GitOps-friendly, no-UI deployments, and multinode OSS setups"
icon: "file-code"
---
<Note>
**Full schema reference:** [`https://www.getbifrost.ai/schema`](https://www.getbifrost.ai/schema)
</Note>
`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.
| Mode | When | Behaviour |
|------|------|-----------|
| **Web UI / database** | No `config.json`, or `config.json` with `config_store` enabled | Full UI available, configuration stored in SQLite or PostgreSQL |
| **File-based (`config.json`)** | `config.json` present, `config_store` disabled | UI disabled, all config loaded from file at startup, restart required for changes |
<Note>
See [Setting Up](/quickstart/gateway/setting-up#two-configuration-modes) for a full explanation of both modes and how `config_store` bootstrapping works.
</Note>
---
## Minimal Working Example
```json
{
"$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:
```bash
# 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:
```bash
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:
```json
{
"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:
```json
{
"$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:
```json
{
"$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"
}
}
}
```
---
## 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.
```json
{
"$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"
}
]
}
]
}
```
<Note>
`access_profiles` is an enterprise capability. For OSS-only deployments, use `governance.virtual_keys` and related governance resources instead.
</Note>
---
## Example Configs
Ready-to-use reference configurations from the [examples/configs](https://github.com/maximhq/bifrost/tree/main/examples/configs) directory on GitHub:
<AccordionGroup>
<Accordion title="Minimal / File-only">
| Example | Description |
|---------|-------------|
| [noconfigstorenologstore](https://github.com/maximhq/bifrost/blob/main/examples/configs/noconfigstorenologstore/config.json) | Bare-minimum file-only mode — no database, no UI, providers loaded from file |
| [partial](https://github.com/maximhq/bifrost/blob/main/examples/configs/partial/config.json) | SQLite config store with a minimal provider setup |
| [v1compat](https://github.com/maximhq/bifrost/blob/main/examples/configs/v1compat/config.json) | `"version": 1` for v1.4.x array semantics (empty = allow all) |
</Accordion>
<Accordion title="Storage">
| Example | Description |
|---------|-------------|
| [withconfigstore](https://github.com/maximhq/bifrost/blob/main/examples/configs/withconfigstore/config.json) | SQLite config store (Web UI enabled) |
| [withconfigstorelogsstorepostgres](https://github.com/maximhq/bifrost/blob/main/examples/configs/withconfigstorelogsstorepostgres/config.json) | PostgreSQL for both config store and logs store |
| [withlogstore](https://github.com/maximhq/bifrost/blob/main/examples/configs/withlogstore/config.json) | SQLite logs store |
| [withobjectstorages3](https://github.com/maximhq/bifrost/blob/main/examples/configs/withobjectstorages3/config.json) | S3 object storage offload for logs |
| [withobjectstoragegcs](https://github.com/maximhq/bifrost/blob/main/examples/configs/withobjectstoragegcs/config.json) | GCS object storage offload for logs |
| [withvectorstoreweaviate](https://github.com/maximhq/bifrost/blob/main/examples/configs/withvectorstoreweaviate/config.json) | Weaviate vector store (with [docker-compose](https://github.com/maximhq/bifrost/blob/main/examples/configs/withvectorstoreweaviate/docker-compose.yml)) |
</Accordion>
<Accordion title="Semantic Cache">
| Example | Description |
|---------|-------------|
| [withsemanticcache](https://github.com/maximhq/bifrost/blob/main/examples/configs/withsemanticcache/config.json) | Semantic cache backed by Weaviate |
| [withsemanticcachevalkey](https://github.com/maximhq/bifrost/blob/main/examples/configs/withsemanticcachevalkey/config.json) | Semantic cache backed by Valkey / Redis |
</Accordion>
<Accordion title="Governance">
| Example | Description |
|---------|-------------|
| [withauth](https://github.com/maximhq/bifrost/blob/main/examples/configs/withauth/config.json) | Admin username/password auth (`governance.auth_config`) |
| [withvirtualkeys](https://github.com/maximhq/bifrost/blob/main/examples/configs/withvirtualkeys/config.json) | Virtual keys with provider/model allowlists |
| [withteamscustomers](https://github.com/maximhq/bifrost/blob/main/examples/configs/withteamscustomers/config.json) | Teams and customers with budgets and rate limits |
| [withroutingrules](https://github.com/maximhq/bifrost/blob/main/examples/configs/withroutingrules/config.json) | CEL-based routing rules for dynamic provider/model selection |
| [withpricingoverridesnostore](https://github.com/maximhq/bifrost/blob/main/examples/configs/withpricingoverridesnostore/config.json) | Pricing overrides in file-only mode |
| [withpricingoverridessqlite](https://github.com/maximhq/bifrost/blob/main/examples/configs/withpricingoverridessqlite/config.json) | Pricing overrides with SQLite config store |
</Accordion>
<Accordion title="Observability">
| Example | Description |
|---------|-------------|
| [withobservability](https://github.com/maximhq/bifrost/blob/main/examples/configs/withobservability/config.json) | Prometheus metrics (telemetry always active, custom labels via `client.prometheus_labels`) |
| [withprompushgateway](https://github.com/maximhq/bifrost/blob/main/examples/configs/withprompushgateway/config.json) | Prometheus Push Gateway for multi-instance deployments |
| [withotel](https://github.com/maximhq/bifrost/blob/main/examples/configs/withotel/config.json) | OpenTelemetry traces and metrics |
</Accordion>
<Accordion title="Plugins & Advanced">
| Example | Description |
|---------|-------------|
| [withdynamicplugin](https://github.com/maximhq/bifrost/blob/main/examples/configs/withdynamicplugin/config.json) | Loading a custom `.so` plugin at startup |
| [withcompat](https://github.com/maximhq/bifrost/blob/main/examples/configs/withcompat/config.json) | SDK compatibility shims (`should_drop_params`, `convert_text_to_chat`) |
| [withframework](https://github.com/maximhq/bifrost/blob/main/examples/configs/withframework/config.json) | Custom model pricing catalog URL and sync interval |
| [withlargepayload](https://github.com/maximhq/bifrost/blob/main/examples/configs/withlargepayload/config.json) | Large payload optimization (streaming without full materialisation) |
| [withwebsocket](https://github.com/maximhq/bifrost/blob/main/examples/configs/withwebsocket/config.json) | WebSocket / Realtime API connection pool tuning |
| [withnginxreverseproxy](https://github.com/maximhq/bifrost/blob/main/examples/configs/withnginxreverseproxy/config.json) | 3-node Bifrost behind NGINX reverse proxy (includes [docker-compose](https://github.com/maximhq/bifrost/blob/main/examples/configs/withnginxreverseproxy/docker-compose.yml), [nginx.conf](https://github.com/maximhq/bifrost/blob/main/examples/configs/withnginxreverseproxy/nginx.conf), [helm values](https://github.com/maximhq/bifrost/blob/main/examples/configs/withnginxreverseproxy/helm-values.yaml), and [k8s ingress](https://github.com/maximhq/bifrost/blob/main/examples/configs/withnginxreverseproxy/k8s-ingress.yaml)) |
| [withpostgresmcpclientsinconfig](https://github.com/maximhq/bifrost/blob/main/examples/configs/withpostgresmcpclientsinconfig/config.json) | MCP client definitions seeded from config.json with PostgreSQL store |
| [encryptionmigration](https://github.com/maximhq/bifrost/blob/main/examples/configs/encryptionmigration/config.json) | Migrating to a new encryption key |
</Accordion>
</AccordionGroup>
---
## Configuration Guides
<CardGroup cols={2}>
<Card title="Schema Reference" icon="brackets-curly" href="/deployment-guides/config-json/schema-reference">
Every top-level key, its type, default, and where it is documented
</Card>
<Card title="Client Configuration" icon="gear" href="/deployment-guides/config-json/client">
Pool size, logging, CORS, header filtering, compat shims, MCP settings
</Card>
<Card title="Provider Setup" icon="plug" href="/deployment-guides/config-json/providers">
OpenAI, Anthropic, Azure, Bedrock, Vertex, Groq, self-hosted
</Card>
<Card title="Storage" icon="database" href="/deployment-guides/config-json/storage">
config_store, logs_store, vector_store — SQLite, PostgreSQL, object storage
</Card>
<Card title="Plugins" icon="puzzle-piece" href="/deployment-guides/config-json/plugins">
Semantic cache, OTel, Maxim, Datadog, custom plugins
</Card>
<Card title="Cluster" icon="circle-nodes" href="/deployment-guides/config-json/cluster">
Cluster mode with static peers or discovery backends (enterprise)
</Card>
<Card title="Governance" icon="shield-check" href="/deployment-guides/config-json/governance">
Virtual keys, budgets, rate limits, routing rules, admin auth
</Card>
<Card title="Guardrails" icon="shield-halved" href="/deployment-guides/config-json/guardrails">
Content moderation providers and CEL-based rules (enterprise)
</Card>
</CardGroup>
---
## Next Steps
1. Configure [provider keys](/providers/supported-providers/overview)
2. Enable [plugins](/plugins/getting-started)
3. Set up [observability](/features/observability/default)
4. Configure [governance](/features/governance/virtual-keys)
5. Deploy [multiple nodes](/deployment-guides/how-to/multinode) with a shared `config.json`