How to Set Up OmniRoute as a Self-Hosted AI Proxy: Complete Installation Guide

You can set up OmniRoute as a self-hosted AI proxy by installing the global NPM package (npm install -g omniroute), connecting free providers through the dashboard, and pointing your OpenAI-compatible clients to http://localhost:20128/v1.

OmniRoute is an open-source AI gateway that consolidates access to 357 providers—including over 90 free tiers—behind a single OpenAI-compatible endpoint. This guide walks you through the complete setup process using the official diegosouzapw/OmniRoute repository, from installation to verifying your first routed request.

What Is OmniRoute?

OmniRoute functions as a self-hosted AI proxy that exposes one unified endpoint (http://localhost:20128/v1) while internally routing requests through a sophisticated 19-strategy combo engine. The system requires zero configuration to start; it works immediately after installation with pre-configured free tiers, then scales to include paid providers, custom routing logic, and advanced resilience settings.

The architecture consists of distinct layers:

• API Routes (src/app/api/v1/) handle Next.js App Router entry points
• Handlers (open-sse/handlers/) manage request processing and SSE streaming
• Executors (open-sse/executors/) dispatch provider-specific HTTP calls
• Translators (open-sse/translator/) convert between OpenAI, Claude, and Gemini payload formats
• Combo Engine (open-sse/services/) orchestrates routing strategies and auto-scoring across 15 live factors
• Resilience Services protect against outages through circuit breakers and cooldown mechanisms

Prerequisites and Installation

You can deploy OmniRoute either as a global NPM package for local development or as a containerized service.

Global NPM Installation

Install the CLI globally and start the server:

npm install -g omniroute
omniroute

The server boots instantly on http://localhost:20128 with the dashboard available at the same address. No API keys or configuration files are required for the initial startup—free providers are available immediately.

Docker Deployment

For production or isolated environments, run the official image:

docker run -d --name omniroute \
  --restart unless-stopped \
  -p 127.0.0.1:20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

This binds the proxy to localhost port 20128 and persists provider data in the named volume.

Connecting Your First AI Providers

Once the server runs, open the dashboard at http://localhost:20128 and navigate to Providers. Add Kiro AI (free Claude access) or OpenCode Free (no authentication required).

After adding providers, generate an API key in Dashboard → Endpoints. You will use this key to authenticate client requests against your local proxy rather than contacting upstream providers directly.

Configuring Your Development Environment

Manual Client Configuration

Point any OpenAI-compatible tool to your self-hosted proxy using these settings:

Base URL: http://localhost:20128/v1
API Key:   <your-generated-key-from-dashboard>
Model:     auto   # triggers smart zero-config routing

This configuration works with Claude Code, Codex, Cursor, Continue, and any other OpenAI-compatible client.

Automated CLI Setup

OmniRoute includes setup commands that automatically configure popular coding CLIs. Available commands include:

• omniroute run claude --model auto – Launches Claude Code with the proxy injected without modifying config files
• omniroute setup-codex – Writes a .codexrc file pointing at http://localhost:20128/v1 and injects your generated API key
• omniroute providers add openai --credential-env OPENAI_API_KEY – Adds OpenAI as a backed provider using your existing environment variable

The CLI manifest at bin/cli/cli-manifest.mjs defines supported targets for the omniroute run command.

How OmniRoute Handles Requests Internally

Understanding the request flow helps troubleshoot routing decisions and resilience behavior.

API Entry Points

Requests enter through Next.js routes such as src/app/api/v1/chat/completions/route.ts or src/app/api/v1/vscode/[token]/models/route.ts. These routes validate JWT tokens, apply CORS policies, and forward payloads to the core handler at open-sse/handlers/chatCore.ts.

Request Translation and Normalization

Before routing, the translator layer normalizes payloads. Files like open-sse/translator/openai.ts and open-sse/translator/anthropic.ts convert between provider-specific schemas, ensuring that a Claude-formatted request reaches OpenAI providers in the correct structure and vice versa.

The Combo Engine and Routing Strategies

The combo engine in open-sse/services/combo.ts implements 19 distinct routing strategies including priority, cost-optimized, fusion, and pipeline. When you specify model: auto, the system uses the LKGP (last-known-good path) strategy, scoring candidates across 15 live factors including health status, quota availability, latency, and cost as documented in docs/routing/AUTO-COMBO.md.

Resilience Mechanisms

Before executing requests, three guards protect against upstream failures:

1. Provider Circuit Breaker – Implemented in src/shared/utils/circuitBreaker.ts, this trips on repeated 5xx errors
2. Connection Cooldown – Managed by open-sse/services/accountFallback.ts, this backs off individual API keys after rate-limit (429) responses
3. Model Lockout – Disables specific models when quota errors occur, preventing repeated failed attempts

Detailed resilience patterns are documented in docs/architecture/RESILIENCE_GUIDE.md.

Verifying Your Setup

Confirm your proxy routes requests correctly:

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

You should receive a JSON array listing all connected provider models. To test chat completions:

curl http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Check response headers for X-OmniRoute-Decision and X-OmniRoute-Cost to verify routing telemetry.

Key Configuration Files and Architecture

File	Purpose
src/app/api/v1/chat/completions/route.ts	Public chat endpoint for all OpenAI-compatible calls
open-sse/services/combo.ts	Routing strategy orchestration and scoring algorithm
src/shared/utils/circuitBreaker.ts	Provider-level circuit breaker implementation
open-sse/services/accountFallback.ts	Connection cooldown and model lockout logic
open-sse/executors/baseExecutor.ts	Base class for provider-specific HTTP dispatch
docs/guides/CLI-INTEGRATIONS.md	Comprehensive CLI setup documentation

Summary

• Install globally with npm install -g omniroute or deploy via Docker with volume persistence
• Connect providers through the web dashboard without writing configuration files
• Route all traffic through http://localhost:20128/v1 using standard OpenAI client libraries
• Leverage automatic resilience through circuit breakers, cooldowns, and model lockouts defined in src/shared/utils/circuitBreaker.ts and open-sse/services/accountFallback.ts
• Use CLI helpers like omniroute setup-codex to automate client configuration

Frequently Asked Questions

Does OmniRoute require API keys to start?

No. OmniRoute functions immediately after installation using pre-configured free-tier providers such as Kiro AI and OpenCode Free. You only need API keys when adding premium providers like OpenAI or Anthropic through the dashboard or CLI.

How does OmniRoute choose which provider to use?

The combo engine in open-sse/services/combo.ts scores available providers across 15 live factors including latency, cost, quota status, and health. When using model: auto, it applies the LKGP (last-known-good path) strategy by default, though you can configure alternative strategies like cost-optimized or fusion.

What happens if a provider fails or rate-limits my request?

OmniRoute implements three resilience layers documented in docs/architecture/RESILIENCE_GUIDE.md: the circuit breaker (src/shared/utils/circuitBreaker.ts) trips on repeated 5xx errors; connection cooldown (open-sse/services/accountFallback.ts) backs off specific keys after 429 responses; and model lockout disables individual models experiencing quota errors.

Can I use OmniRoute with Claude Code or other non-OpenAI tools?

Yes. OmniRoute presents an OpenAI-compatible API, but the translator layer (open-sse/translator/) converts payloads between formats. Use omniroute run claude --model auto to launch Claude Code with automatic proxy injection, or manually configure any OpenAI-compatible client to use http://localhost:20128/v1 as the base URL.

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