Setting Up

Get Bifrost running as an HTTP API gateway in 30 seconds with zero configuration. Perfect for any programming language.

30-Second Setup

Get Bifrost running as a blazing-fast HTTP API gateway with zero configuration. Connect to any AI provider (OpenAI, Anthropic, Bedrock, and more) through a unified API that follows OpenAI request/response format.

1. Choose Your Setup Method

Both options work perfectly - choose what fits your workflow:

NPX Binary

# Install and run locally
npx -y @maximhq/bifrost

# Install a specific version
npx -y @maximhq/bifrost --transport-version v1.3.9

Docker

# Pull and run Bifrost HTTP API
docker pull maximhq/bifrost
docker run -p 8080:8080 maximhq/bifrost

# Pull a specific version
docker pull maximhq/bifrost:v1.3.9
docker pull maximhq/bifrost:v1.3.9-amd64
docker pull maximhq/bifrost:v1.3.9-arm64

For Data Persistence

# For configuration persistence across restarts
docker run -p 8080:8080 -v $(pwd)/data:/app/data maximhq/bifrost

2. Configuration Flags

Flag	Default	NPX	Docker	Description
port	8080	-port 8080	-e APP_PORT=8080 -p 8080:8080	HTTP server port
host	localhost	-host 0.0.0.0	-e APP_HOST=0.0.0.0	Host to bind server to
log-level	info	-log-level info	-e LOG_LEVEL=info	Log level (debug, info, warn, error)
log-style	json	-log-style json	-e LOG_STYLE=json	Log style (pretty, json)

Understanding App Directory

The -app-dir flag determines where Bifrost stores all its data:

# Specify custom directory
npx -y @maximhq/bifrost -app-dir ./my-bifrost-data

# If not specified, creates in your OS config directory:
# • Linux/macOS: ~/.config/bifrost
# • Windows: %APPDATA%\bifrost

What’s stored in app-dir:

• config.json - Configuration file (optional)
• config.db - SQLite database for UI configuration
• logs.db - Request logs database

Note: When using Bifrost via Docker, the volume you mount will be used as the app-dir.

3. Open the Web Interface

Navigate to http://localhost:8080 in your browser:

# macOS
open http://localhost:8080

# Linux
xdg-open http://localhost:8080

# Windows
start http://localhost:8080

🖥️ The Web UI provides:

• Visual provider setup - Add API keys with clicks, not code
• Real-time configuration - Changes apply immediately
• Live monitoring - Request logs, metrics, and analytics
• Governance management - Virtual keys, usage budgets, and more

4. Test Your First API Call

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

🎉 That’s it! Bifrost is running and ready to route AI requests.

What Just Happened?

1. Zero Configuration Start: Bifrost launched without any config files - everything can be configured through the Web UI or API
2. OpenAI-Compatible API: All Bifrost APIs follow OpenAI request/response format for seamless integration
3. Unified API Endpoint: /v1/chat/completions works with any provider (OpenAI, Anthropic, Bedrock, etc.)
4. Provider Resolution: openai/gpt-4o-mini tells Bifrost to use OpenAI’s GPT-4o Mini model. You can also use bare model names like gpt-4o-mini, Bifrost will automatically resolve the provider via the Model Catalog
5. Automatic Routing: Bifrost handles authentication, rate limiting, and request routing automatically

---

Two Configuration Modes

Bifrost supports two configuration approaches:

How config and database state interact:

• Entities defined in config.json are stored with a content-based hash on first load.
• Changes made later through the UI or API are persisted to the database and survive pod restarts, scale-ups, and redeployments.
• Re-applying the same config.json does not overwrite those database changes, because the content hash is unchanged. If you edit an entity directly in config.json, its hash changes and the file-based definition overwrites the database copy.

Mode 1: Web UI Configuration

When the UI is available:

• No config.json file exists (Bifrost auto-creates SQLite database)
• config.json exists with config_store configured

Mode 2: File-based Configuration

You can view entire config schema here

When to use: Advanced setups, GitOps workflows, or when UI is not needed

Create config.json in your app directory:

{
  "$schema": "https://www.getbifrost.ai/schema",
  "client": {
    "drop_excess_requests": false
  },
  "providers": {
    "openai": {
      "keys": [
        {
          "name": "openai-key-1",
          "value": "env.OPENAI_API_KEY",
          "models": ["gpt-4o-mini", "gpt-4o"],
          "weight": 1.0
        }
      ]
    }
  },
  "config_store": {
    "enabled": true,
    "type": "sqlite",
    "config": {
      "path": "./config.db"
    }
  }
}

Without config_store in config.json:

• UI is disabled - no real-time configuration possible
• Read-only mode - config.json is never modified
• Memory-only - all configurations loaded into memory at startup
• Restart required - changes to config.json only apply after restart

With config_store in config.json:

• UI is enabled - full real-time configuration via web interface
• Database check - Bifrost reconciles config.json against the config store using a content-based hash per entity
  • Empty DB: Bootstraps database with config.json settings, then uses DB for runtime reads
  • Existing DB: Compares each entity’s file hash to the stored ConfigHash. If the hash is unchanged, the DB copy is kept (UI/API edits are preserved). If you edit an entity in config.json so its hash changes, the file definition overwrites the DB copy for that entity. Entries added only via the UI/API (not present in config.json) are always preserved.
• Persistent storage - all changes saved to database immediately

The Three Stores Explained:

• Config Store: Stores provider configs, API keys, MCP settings - Required for UI functionality
• Logs Store: Stores request logs shown in UI - Optional, can be disabled
• Vector Store: Used for semantic caching - Optional, can be disabled

PostgreSQL UTF8 Requirement

The minimum PostgreSQL version required is 16 or above.

For the log store, Bifrost creates materialized views to improve analytics performance. Ensure that the PostgreSQL user has the necessary permissions to perform these operations on the target schema.

If you use PostgreSQL for config_store or logs_store, the target database must use UTF8 encoding.

Use template0 when creating the database so PostgreSQL applies UTF8 and locale settings explicitly:

CREATE DATABASE bifrost
  WITH TEMPLATE template0
       ENCODING 'UTF8'
       LC_COLLATE '<your-locale>'
       LC_CTYPE '<your-locale>';

Use locale names that exist in your Postgres image/host (for example, en_US.UTF-8, C.UTF-8, or another installed UTF-8 locale).

Verify the database encoding:

SELECT datname, pg_encoding_to_char(encoding) AS encoding
FROM pg_database
WHERE datname = 'bifrost';

If the database is not UTF8, Bifrost startup/migrations can fail with:

simple protocol queries must be run with client_encoding=UTF8

If you already created a SQL_ASCII database, create a new UTF8 database and update your Bifrost DB config to point to it.

---

Next Steps

Now that you have Bifrost running, explore these focused guides:

Essential Topics

• Provider Configuration - Multiple providers, automatic failovers & load balancing
• Integrations - Drop-in replacements for OpenAI, Anthropic, and GenAI SDKs
• Multimodal Support - Support for text, images, audio, and streaming, all behind a common interface.

Advanced Topics

• Tracing - Logging requests for monitoring and debugging
• MCP Tools - Enable AI models to use external tools (filesystem, web search, databases)
• Governance - Usage tracking, rate limiting, and cost control
• Deployment - Production setup and scaling

---

Happy building with Bifrost! 🚀