Skip to main content
This guide walks you through setting up the Bifrost repository for local development, from prerequisites to running your first development server.

​
Prerequisites

Before setting up the repository, ensure you have the following tools installed:

​
Go (Required)

Bifrost requires Go 1.21+ for development. 
# Check if Go is installed
go version

# If not installed, download from https://golang.org/dl/
# Or use package managers:

# macOS (Homebrew)
brew install go

# Ubuntu/Debian
sudo apt update && sudo apt install golang-go

# Windows (Chocolatey)
choco install golang

​
Node.js and npm (Required for UI development)

The UI components require Node.js 18+ and npm. 
# Check versions
node --version
npm --version

# Install via package managers:

# macOS (Homebrew)
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows (Chocolatey)
choco install nodejs

​
Make (Required)

Required for running development commands via the Makefile. 
# Check if make is installed
make --version
If make is not installed, follow our Install make command guide.

​
Docker (Optional)

Only needed if you plan to build Docker images or test containerized deployments. 
# Check if Docker is installed
docker --version

# Install from https://docs.docker.com/get-docker/

​
Air (Auto-installed)

Air provides hot reloading during development. The Makefile will install it automatically when needed.

​
Clone the Repository

# Clone the repository
git clone https://github.com/maximhq/bifrost.git
cd bifrost

# Verify the repository structure
ls -la
You should see the main directories: core/, framework/, transports/, ui/, plugins/, docs/, etc.

​
Repository Structure

Bifrost uses a modular architecture with the following structure: 
bifrost/
├── core/                # Core functionality and shared components
│   ├── providers/       # Provider-specific implementations (OpenAI, Anthropic, etc.)
│   ├── schemas/         # Interfaces and structs used throughout Bifrost
│   └── bifrost.go       # Main Bifrost implementation
├── framework/           # Framework components for common functionality
│   ├── configstore/     # Configuration storages
│   ├── logstore/        # Request logging storages
│   └── vectorstore/     # Vector storages
├── transports/          # HTTP gateway and other interface layers
│   └── bifrost-http/    # HTTP transport implementation
├── ui/                  # Web interface for HTTP gateway
├── plugins/             # First party plugins
├── docs/                # Documentation and guides
└── tests/               # Comprehensive test suites
The system uses a provider-agnostic approach with well-defined interfaces in core/schemas/ for easy extension to new AI providers. Learn More About the Architecture:

​
Development Environment Setup

The fastest way to get started is using the complete development environment: 
# Start complete development environment (UI + API with hot reload)
make dev
This command will:
  1. Install UI dependencies automatically
  2. Install Air for hot reloading
  3. Set up the Go workspace with local modules
  4. Start the Next.js development server (port 3000)
  5. Start the API server with UI proxy (port 8080)
Access the application at: http://localhost:8080
The make dev command handles all setup automatically. You can skip the manual setup steps below if this works for you.

​
Manual Setup (Alternative)

If you prefer to set up components manually:

​
1. Install UI Dependencies

# Install UI dependencies and tools
make install-ui

​
2. Install Air for Hot Reloading

# Install Air if not already installed
make install-air

​
3. Set Up Go Workspace

# Set up Go workspace with all local modules
make setup-workspace
This creates a go.work file that links all local modules for development.

​
4. Build the Application

# Build UI and binary
make build

​
5. Run the Application

# Run without hot reload
make run

# Or with hot reload (development)
make dev

​
Available Make Commands

The Makefile provides numerous commands for development:

​
Development Commands

make dev          # Start complete development environment (recommended)
make build        # Build UI and bifrost-http binary
make run          # Build and run (no hot reload)
make clean        # Clean build artifacts

​
Testing Commands

make test         # Run bifrost-http tests
make test-core    # Run core tests
make test-plugins # Run plugin tests
make test-all     # Run all tests

​
Workspace Management

make setup-workspace  # Set up Go workspace for local development
make work-clean      # Remove local go.work files

​
UI Commands

make install-ui   # Install UI dependencies
make build-ui     # Build UI for production

​
Docker Commands

make build-docker-image  # Build Docker image
make docker-run         # Run Docker container

​
Documentation

make docs         # Start local documentation server

​
Code Quality

make lint         # Run linter for Go code
make fmt          # Format Go code

​
Environment Variables

You can customize the development environment with these variables: 
# Server configuration
HOST=localhost                    # Server host (default: localhost)
PORT=8080                        # Server port (default: 8080)

# Logging
LOG_STYLE=json                   # Logger format: json|pretty (default: json)
LOG_LEVEL=info                   # Logger level: debug|info|warn|error (default: info)

# Prometheus
PROMETHEUS_LABELS="env=dev"      # Labels for Prometheus metrics

# App directory (for containers)
APP_DIR=/app/data               # App data directory
Example with custom settings: 
PORT=3001 LOG_STYLE=pretty LOG_LEVEL=debug make dev

​
Understanding Bifrost Architecture

Before diving into development, it’s helpful to understand how Bifrost works internally. The architecture documentation provides detailed insights into:

​
Core Components

​
Framework Layer

​
Plugins & Transports

Reading the architecture documentation will help you understand where to make changes and how different components interact.

​
Development Workflow

​
1. Start Development Environment

make dev

​
2. Make Your Changes

  • Core changes: Edit files in core/
  • API changes: Edit files in transports/bifrost-http/
  • UI changes: Edit files in ui/
  • Plugin changes: Edit files in plugins/

​
3. Test Your Changes

# Run relevant tests
make test           # HTTP transport tests
make test-core      # Core functionality tests
make test-plugins   # Plugin tests
make test-all       # All tests

​
4. Verify Code Quality

# Format code
make fmt

# Run linter
make lint

​
5. Build for Production

# Build everything
make build

# Or build Docker image
make build-docker-image

​
Troubleshooting

​
Common Issues

Go workspace issues: 
# Reset the workspace
make work-clean
make setup-workspace
UI dependency issues: 
# Clean and reinstall UI dependencies
rm -rf ui/node_modules ui/.next
make install-ui
Port conflicts: 
# Use different ports
PORT=9090 make dev
Hot reload not working: 
# Ensure Air is installed
which air || go install github.com/air-verse/air@latest

# Check if .air.toml exists in transports/bifrost-http/
ls transports/bifrost-http/.air.toml

​
Getting Help

  • Check logs: Development logs appear in your terminal
  • Verify prerequisites: Ensure Go, Node.js, and make are properly installed
  • Clean build: Run make clean and try again
  • Discord: Join our Discord community for real-time help

​
Next Steps

Once your development environment is running:
  1. Explore the UI: Visit http://localhost:8080 to see the web interface
  2. Make API calls: Test the API endpoints at http://localhost:8080/v1/
  3. Understand the architecture: Read our request flow documentation to understand how Bifrost works internally
  4. Read the documentation: Check out our complete documentation
  5. Review contribution guidelines: See our code conventions and PR guidelines

​
Quick Reference

# Essential commands for daily development
make dev          # Start development environment
make test-all     # Run all tests  
make fmt          # Format code
make clean        # Clean build artifacts
make help         # Show all available commands
Happy coding! 🚀