--- title: "Setting Up" description: "Get Bifrost running as an HTTP API gateway in 30 seconds with zero configuration. Perfect for any programming language." icon: "play" --- ![Bifrost Gateway Installation](../../media/getting-started.png) ## 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 ```bash # Install and run locally npx -y @maximhq/bifrost # Install a specific version npx -y @maximhq/bifrost --transport-version v1.3.9 ``` #### Docker ```bash # 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** ```bash # 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: ```bash # 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: ```bash # 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 ```bash 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 5. **Automatic Routing**: Bifrost handles authentication, rate limiting, and request routing automatically --- ## Two Configuration Modes Bifrost supports **two configuration approaches** - you cannot use both simultaneously: ### Mode 1: Web UI Configuration ![Configuration via UI](../../media/ui-config.png) **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](https://www.getbifrost.ai/schema) **When to use:** Advanced setups, GitOps workflows, or when UI is not needed Create `config.json` in your app directory: ```json { "$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 checks if config store database exists and has data - **Empty DB**: Bootstraps database with `config.json` settings, then uses DB exclusively - **Existing DB**: Uses database directly, **ignores** `config.json` configurations - **Persistent storage** - all changes saved to database immediately **Important for Advanced Users:** If you want database persistence but prefer not to use the UI, note that modifying `config.json` after initial bootstrap has no effect when `config_store` is enabled. Use the public HTTP APIs to make configuration changes instead. **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: ```sql CREATE DATABASE bifrost WITH TEMPLATE template0 ENCODING 'UTF8' LC_COLLATE '' LC_CTYPE ''; ``` 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: ```sql 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: ```text 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](./provider-configuration)** - Multiple providers, automatic failovers & load balancing - **[Integrations](../../integrations/what-is-an-integration)** - Drop-in replacements for OpenAI, Anthropic, and GenAI SDKs - **[Multimodal Support](./multimodal)** - Support for text, images, audio, and streaming, all behind a common interface. ### Advanced Topics - **[Tracing](../../features/observability/default)** - Logging requests for monitoring and debugging - **[MCP Tools](../../mcp/overview)** - Enable AI models to use external tools (filesystem, web search, databases) - **[Governance](../../features/governance/virtual-keys)** - Usage tracking, rate limiting, and cost control - **[Deployment](../../deployment-guides/k8s)** - Production setup and scaling --- **Happy building with Bifrost!** 🚀