How to Deploy OmniRoute: Complete Deployment Guide for Docker, Fly.io, and Edge Platforms

Deploy OmniRoute using Docker containers, Fly.io VMs, or serverless edge platforms by configuring environment variables, building from the provided Dockerfile, and running platform-specific deploy commands.

OmniRoute is a Next.js 16 application that serves as a unified AI routing proxy. This guide explains how to deploy OmniRoute across multiple hosting environments—from local Docker containers to global edge platforms—based on the official source code in diegosouzapw/OmniRoute.

---

Deployment Architecture Overview

OmniRoute's deployment model centers on stateless containers with optional persistent storage for SQLite. The application exposes its API through Next.js server routes under src/app/api/v1/, while provider-specific logic runs through the open-sse workspace. This architecture makes OmniRoute suitable for containerized deployments where the data directory mounts as a persistent volume.

Key deployment components include:

• Dockerfile – builds reproducible production images
• docker-compose.yml – orchestrates multi-service setups
• fly.toml – configures Fly.io VM deployments
• wrangler.toml – enables Cloudflare Workers edge deployment

---

Method 1: Docker Deployment

Docker is the general-purpose container format used for most OmniRoute deployments. The process is documented in docs/ops/DEPLOYMENT_GUIDE.md.

Build and Run Locally

# Build the production image

docker build -t omniroute:latest .

# Run with environment configuration

docker run -p 3000:3000 --env-file .env omniroute:latest

Source: Docker build/run commands at DEPLOYMENT_GUIDE.md#L45-L48

Production Docker Setup

For production environments, wrap the container with a process manager like pm2 or systemd to ensure the container stays alive.

Docker Compose Configuration

Use the provided docker-compose.yml for multi-service orchestration:

services:
  omniroute:
    image: omniroute:latest
    ports:
      - "3000:3000"
    env_file: .env
    volumes:
      - omniroute-data:/data
volumes:
  omniroute-data:

Source: Compose example at DEPLOYMENT_GUIDE.md#L112-L114

---

Method 2: Fly.io Deployment

Fly.io provides edge-hosted VMs ideal for low-latency AI proxy deployments. The fly.toml configuration file controls app settings, with app = 'omniroute' determining which Fly application receives deployments.

Deploy Steps

# Install Fly CLI

brew install flyctl

# or

curl -L https://fly.io/install.sh | sh

# Launch new app (creates fly.toml if absent)

flyctl launch --name my-omniroute

# Deploy current codebase

flyctl deploy

Source: Fly.io workflow at FLY_IO_DEPLOYMENT_GUIDE.md#L9-L13 and app configuration at FLY_IO_DEPLOYMENT_GUIDE.md#L56

Docker-to-Fly Workflow

For custom images, push to Fly's registry first:

docker build -t omniroute:latest .
docker tag omniroute:latest registry.fly.io/my-omniroute:latest
docker push registry.fly.io/my-omniroute:latest
flyctl deploy --image registry.fly.io/my-omniroute:latest

---

Method 3: Cloudflare Workers (Wrangler)

Deploy OmniRoute's Bifrost sidecar to Cloudflare's edge network for serverless execution.

npx wrangler deploy

Source: Wrangler deploy command at VM_DEPLOYMENT_GUIDE.md#L410

The wrangler.toml file configures worker routes, environment variables, and KV namespaces for edge caching.

---

Method 4: Vercel Deployment

OmniRoute builds natively on Vercel with zero configuration for standard Next.js apps.

# Install Vercel CLI

npm i -g vercel

# Link and deploy

vercel --prod

Vercel automatically detects next.config.js and runs npm run build, serving output from the .next/ directory.

Source: Vercel environment configuration referenced at ENVIRONMENT.md#L1038

---

Essential Environment Variables

Configure these variables before deployment:

Variable	Purpose	Example
NEXT_PUBLIC_BASE_URL	Public hostname for OAuth callbacks and generated links	https://omniroute.example.com
OMNIROUTE_BASE_PATH	Sub-path hosting (optional)	/omniroute
CORS_ALLOWED_ORIGINS	Browser API access control	https://app.example.com,https://admin.example.com
OMNIROUTE_LOCAL_ENDPOINTS_ENABLED	Toggle internal /api/local/* routes	0 (production), 1 (development)
OMNIROUTE_NO_SUDO	Root-less container compatibility	1
BIFROST_ENABLED	High-throughput sidecar activation	1

Source: Complete environment reference at ENVIRONMENT.md#L46-L299

---

Complete Deployment Example: Docker + Fly.io

# Build production image

docker build -t omniroute:latest .

# Create Fly.io application

flyctl launch --name my-omniroute --copy-config

# Push to Fly registry

docker tag omniroute:latest registry.fly.io/my-omniroute:latest
docker push registry.fly.io/my-omniroute:latest

# Deploy with custom image

flyctl deploy --image registry.fly.io/my-omniroute:latest

# Configure secrets

flyctl secrets set \
  NEXT_PUBLIC_BASE_URL=https://omniroute.example.com \
  OMNIROUTE_BASE_PATH=/omniroute \
  CORS_ALLOWED_ORIGINS=https://myclient.com \
  BIFROST_ENABLED=1

Verify deployment by requesting the models endpoint:

curl https://omniroute.example.com/api/v1/models

---

Key Deployment Files

File	Location	Purpose
Dockerfile	Repository root	Production container image definition
Dockerfile.dev	Repository root	Development container with hot reload
docker-compose.yml	Repository root	Multi-service orchestration template
fly.toml	Repository root	Fly.io VM configuration
wrangler.toml	Repository root	Cloudflare Workers deployment config
docs/ops/DEPLOYMENT_GUIDE.md	docs/ops/	Primary Docker deployment documentation
docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md	docs/ops/	Fly.io-specific deployment steps
docs/ops/VM_DEPLOYMENT_GUIDE.md	docs/ops/	VM and Wrangler deployment instructions
docs/reference/ENVIRONMENT.md	docs/reference/	Complete environment variable reference
src/app/api/v1/relay/chat/completions/bifrost/route.ts	src/app/api/v1/relay/chat/completions/bifrost/	Bifrost high-throughput entry point
src/lib/db/core.ts	src/lib/db/	SQLite database initialization and DATA_DIR handling

---

Summary

• Docker provides the most flexible deployment path—build once, run anywhere with docker build and docker run
• Fly.io offers managed edge VMs with flyctl deploy and configuration through fly.toml
• Cloudflare Workers enable serverless edge deployment via npx wrangler deploy
• Vercel delivers zero-config Next.js hosting with automatic builds
• Always configure NEXT_PUBLIC_BASE_URL and CORS_ALLOWED_ORIGINS before deploying to production
• Mount persistent volumes for SQLite data in containerized environments

---

Frequently Asked Questions

What is the minimum infrastructure needed to run OmniRoute in production?

OmniRoute requires a container runtime (Docker) or Node.js 22+ environment with at least 512MB RAM and persistent storage for the SQLite database file. For high-traffic deployments, enable the Bifrost sidecar and allocate 1GB+ RAM with CPU scaling.

How do I configure OmniRoute when hosting behind a reverse proxy?

Set NEXT_PUBLIC_BASE_URL to your public HTTPS endpoint and OMNIROUTE_BASE_PATH to any sub-path prefix. These variables ensure OAuth callbacks, generated links, and CORS headers reference the correct external addresses rather than internal container hostnames.

Can I deploy OmniRoute without Docker?

Yes—OmniRoute runs as a standard Next.js application. Install dependencies with npm ci, build with npm run build, and start with npm start. However, Docker is recommended for production to ensure consistent environments and simplify rollbacks across deployment targets.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}