263 lines
8.5 KiB
Plaintext
263 lines
8.5 KiB
Plaintext
---
|
|
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"
|
|
---
|
|
|
|
|
|
|
|
## 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
|
|
|
|
<video width="100%" controls>
|
|
<source src="https://github.com/maximhq/bifrost/raw/refs/heads/main/docs/media/run-npx.mp4" type="video/mp4" />
|
|
Your browser does not support the video tag.
|
|
</video>
|
|
|
|
```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
|
|
|
|
|
|
|
|
**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
|
|
|
|
<Note>You can view entire config schema [here](https://www.getbifrost.ai/schema)</Note>
|
|
|
|
**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
|
|
|
|
<Note>
|
|
The minimum PostgreSQL version required is 16 or above.
|
|
</Note>
|
|
|
|
<Note>
|
|
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.
|
|
</Note>
|
|
|
|
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 '<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:
|
|
|
|
```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!** 🚀
|