OmniRoute Setup Guide: Install via npm or Docker & Connect Your Coding Tools

OmniRoute is a self-hosted AI gateway: a single OpenAI-compatible endpoint that routes requests across many LLM providers, with smart routing, load balancing, retries and fallbacks. It runs entirely on your own hardware via npm, Docker, desktop or phone. This guide walks you through installation, first-run setup, and connecting your coding tools — all based on OmniRoute's official docs.

Step 1Prerequisites

• Node.js + npm — if you install via npm; or
• Docker — if you prefer a container.
• An OpenAI-compatible coding tool you want to route through OmniRoute: Claude Code, Codex, Cursor, Cline, Copilot, Continue, etc.

Step 2Install OmniRoute

Option A — npm (global)

npm install -g omniroute

Option B — Docker

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

This maps port 20128 and persists data in the omniroute-data volume.

Option C — From source

cp .env.example .env && npm install
PORT=20128 npm run dev

Step 3First-run setup & dashboard

Run the guided first-run wizard:

omniroute setup

Then start the gateway + dashboard:

omniroute

By default OmniRoute serves on port 20128:

• Dashboard: http://localhost:20128
• OpenAI-compatible API endpoint: http://localhost:20128/v1

Step 4Connect your coding tool

OmniRoute exposes an OpenAI-compatible endpoint, so any tool that accepts a custom base URL works. In your tool's settings:

• Base URL: http://localhost:20128/v1
• API Key: copy it from Dashboard → Endpoints
• Model: auto for smart routing, or a specific provider/model

Compatible tools include Claude Code, Codex, Cursor, Cline, Copilot and Continue.

Step 5Verify your setup

Diagnose providers, ports and native dependencies:

omniroute doctor

For an interactive chat client in the terminal:

omniroute chat

Handy CLI commands

OmniRoute ships a command-line cockpit. A few useful ones:

• omniroute — serve gateway + dashboard
• omniroute setup — guided first-run wizard
• omniroute doctor — diagnose providers and ports
• omniroute chat — interactive TUI chat client

Additional command groups referenced in the docs include providers, oauth, keys, models, cache, compression, cost, usage, health, logs, mcp and a2a.

FAQ

How do I install OmniRoute?

npm: npm install -g omniroute; Docker: the docker run … diegosouzapw/omniroute:latest command above; or from source with cp .env.example .env && npm install then PORT=20128 npm run dev.

What port does it use?

20128 by default (dashboard at http://localhost:20128, API at /v1); change it with PORT.

How do I connect my coding tool?

Base URL http://localhost:20128/v1, API key from Dashboard → Endpoints, model auto.

Where is data stored?

DATA_DIR, defaulting to ~/.omniroute; credentials encrypted with AES-256-GCM.

Where are the full docs?

This guide covers install and first connect. For provider-specific setup, advanced commands and options, see the official repo: github.com/diegosouzapw/OmniRoute.