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

> Install OmniRoute as a self-hosted AI proxy easily with NPM. Connect free providers and route your OpenAI-compatible clients. Get the complete installation guide now.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-28

---

**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:

```bash
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:

```bash
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:

```text
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts).

### Request Translation and Normalization

Before routing, the **translator** layer normalizes payloads. Files like [`open-sse/translator/openai.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/translator/openai.ts) and [`open-sse/translator/anthropic.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts), this trips on repeated 5xx errors
2. **Connection Cooldown** – Managed by [`open-sse/services/accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/architecture/RESILIENCE_GUIDE.md).

## Verifying Your Setup

Confirm your proxy routes requests correctly:

```bash
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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) | Public chat endpoint for all OpenAI-compatible calls |
| [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) | Routing strategy orchestration and scoring algorithm |
| [`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts) | Provider-level circuit breaker implementation |
| [`open-sse/services/accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/accountFallback.ts) | Connection cooldown and model lockout logic |
| [`open-sse/executors/baseExecutor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/baseExecutor.ts) | Base class for provider-specific HTTP dispatch |
| [`docs/guides/CLI-INTEGRATIONS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts) and [`open-sse/services/accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/architecture/RESILIENCE_GUIDE.md): the **circuit breaker** ([`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts)) trips on repeated 5xx errors; **connection cooldown** ([`open-sse/services/accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.