🚀 OmniRoute — The Free AI Gateway (Kiswahili)

Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.

How OmniRoute solves it:

• Smart 4-Tier Fallback — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
• Provider Limits Tracking — Cached quota snapshots refresh on a server-side schedule (default PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70) with manual refresh available in the UI
• Multi-Account Support — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
• Custom Combos — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay)
• Structured Combo Builder — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets
• Quota-Aware P2C — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use
• Codex Business Quotas — Business/Team workspace quota monitoring directly in the dashboard

OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.

How OmniRoute solves it:

• Unified Endpoint — A single http://localhost:20128/v1 serves as proxy for all 100+ providers
• Format Translation — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
• Response Sanitization — Strips non-standard fields (x_groq, usage_breakdown, service_tier) that break OpenAI SDK v1.83+
• Role Normalization — Converts developer → system for non-OpenAI providers; system → user for GLM/ERNIE
• Think Tag Extraction — Extracts <think> blocks from models like DeepSeek R1 into standardized reasoning_content
• Structured Output for Gemini — json_schema → responseMimeType/responseSchema automatic conversion
• stream defaults to false — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs

Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like unsupported_country_region_territory during OAuth and API connections. This is especially frustrating for developers from developing countries.

How OmniRoute solves it:

• 3-Level Proxy Config — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key
• Color-Coded Proxy Badges — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP
• OAuth Token Exchange Through Proxy — OAuth flow also goes through the proxy, solving unsupported_country_region_territory
• Connection Tests via Proxy — Connection tests use the configured proxy (no more direct bypass)
• SOCKS5 Support — Full SOCKS5 proxy support for outbound routing
• TLS Fingerprint Spoofing — Browser-like TLS fingerprint via wreq-js to bypass bot detection
• 🔏 CLI Fingerprint Matching — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth and IP masking simultaneously

Not everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.

How OmniRoute solves it:

• Ollama Cloud — Cloud-hosted Ollama models at api.ollama.com with free "Light usage" tier; use ollamacloud/<model> prefix
• Free-Only Combos — Chain if/kimi-k2-thinking → qw/qwen3-coder-plus = $0/month with zero downtime
• NVIDIA NIM Free Access — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)
• Cost Optimized Strategy — Routing strategy that automatically chooses the cheapest available provider

When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.

How OmniRoute solves it:

• API Key Management — Generation, rotation, and scoping per provider with a dedicated /dashboard/api-manager page
• Model-Level Permissions — Restrict API keys to specific models (openai/*, wildcard patterns), with Allow All/Restrict toggle
• API Endpoint Protection — Require a key for /v1/models and block specific providers from the listing
• Auth Guard + CSRF Protection — All dashboard routes protected with withAuth middleware + CSRF tokens
• Rate Limiter — Per-IP rate limiting with configurable windows
• IP Filtering — Allowlist/blocklist for access control
• Prompt Injection Guard — Sanitization against malicious prompt patterns
• AES-256-GCM Encryption — Credentials encrypted at rest

AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.

How OmniRoute solves it:

• Request Queue & Pacing — Per-connection request buckets smooth bursts before they hit upstream rate caps
• Connection Cooldown — A single connection cools down after retryable failures with optional upstream Retry-After hints and exponential backoff
• Provider Circuit Breaker — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped 429 rate limits stay in Connection Cooldown
• Wait For Cooldown — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically
• Anti-Thundering Herd — Mutex + semaphore protection against concurrent retry storms
• Combo Fallback Chains — If the primary provider fails, automatically falls through the chain with no intervention
• Health Dashboard — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency

How OmniRoute solves it:

• CLI Tools Dashboard — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
• GitHub Copilot Config Generator — Generates chatLanguageModels.json for VS Code with bulk model selection
• Onboarding Wizard — Guided 4-step setup for first-time users
• One endpoint, all models — Configure http://localhost:20128/v1 once, access 100+ providers

Claude Code, Codex, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with client_secret is missing, redirect_uri_mismatch, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.

How OmniRoute solves it:

• Auto Token Refresh — OAuth tokens refresh in background before expiration
• OAuth 2.0 (PKCE) Built-in — Automatic flow for Claude Code, Codex, Copilot, Kiro, Qwen, Qoder
• Multi-Account OAuth — Multiple accounts per provider via JWT/ID token extraction
• OAuth LAN/Remote Fix — Private IP detection for redirect_uri + manual URL mode for remote servers
• OAuth Behind Nginx — Uses window.location.origin for reverse proxy compatibility
• Remote OAuth Guide — Step-by-step guide for Google Cloud credentials on VPS/Docker

Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.

How OmniRoute solves it:

• Cost Analytics Dashboard — Per-token cost tracking and budget management per provider
• Budget Limits per Tier — Spending ceiling per tier that triggers automatic fallback
• Per-Model Pricing Configuration — Configurable prices per model
• Usage Statistics Per API Key — Request count and last-used timestamp per key
• Analytics Dashboard — Stat cards, model usage chart, provider table with success rates and latency

When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.

How OmniRoute solves it:

• Unified Logs Dashboard — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console
• Console Log Viewer — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter
• SQLite Summary Logs — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite
• Translator Playground — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)
• Request Telemetry — p50/p95/p99 latency + X-Request-Id tracing
• File-Based Detail Artifacts — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in DATA_DIR/call_logs/ and rotate independently of SQLite summaries
• System Info Report — npm run system-info generates system-info.txt with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.

Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, EACCES on directories, port conflicts, and cross-platform builds add friction.

How OmniRoute solves it:

• npm global install — npm install -g omniroute && omniroute — done
• Docker Multi-Platform — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)
• Docker Compose Profiles — base (no CLI tools) and cli (with Claude Code, Codex, OpenClaw)
• Electron Desktop App — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode
• Split-Port Mode — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)
• Cloud Sync — Config synchronization across devices via Cloudflare Workers
• DB Backups — Automatic backup, restore, export and import of all settings, with DISABLE_SQLITE_AUTO_BACKUP for externally managed backups

Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.

How OmniRoute solves it:

• Dashboard i18n — 30 Languages — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English
• RTL Support — Right-to-left support for Arabic and Hebrew
• Multi-Language READMEs — 30 complete documentation translations
• Language Selector — Globe icon in header for real-time switching

AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.

How OmniRoute solves it:

• Embeddings — /v1/embeddings with 6 providers and 9+ models
• Image Generation — /v1/images/generations with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)
• Text-to-Video — /v1/videos/generations — ComfyUI (AnimateDiff, SVD) and SD WebUI
• Text-to-Music — /v1/music/generations — ComfyUI (Stable Audio Open, MusicGen)
• Audio Transcription — /v1/audio/transcriptions — Whisper + Nvidia NIM, HuggingFace, Qwen3
• Text-to-Speech — /v1/audio/speech — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + existing providers
• Moderations — /v1/moderations — Content safety checks
• Reranking — /v1/rerank — Document relevance reranking
• Responses API — Full /v1/responses support for Codex

Developers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.

How OmniRoute solves it:

• LLM Evaluations — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal
• 4 Match Strategies — exact, contains, regex, custom (JS function)
• Translator Playground Test Bench — Batch testing with multiple inputs and expected outputs, cross-provider comparison
• Chat Tester — Full round-trip with visual response rendering
• Live Monitor — Real-time stream of all requests flowing through the proxy

As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.

How OmniRoute solves it:

• Semantic Cache — Two-tier cache (signature + semantic) reduces cost and latency
• Request Idempotency — 5s deduplication window for identical requests
• Rate Limit Detection — Per-provider RPM, min gap, and max concurrent tracking
• Request Queue & Pacing — Configurable queue, pacing, and concurrency defaults in Settings → Resilience
• API Key Validation Cache — 3-tier cache for production performance
• Health Dashboard with Telemetry — p50/p95/p99 latency, cache stats, uptime

Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.

How OmniRoute solves it:

• System Prompt Injection — Global prompt applied to all requests
• Thinking Budget Validation — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)
• 9 Routing Strategies — Global strategies that determine how requests are distributed
• Wildcard Router — provider/* patterns route dynamically to any provider
• Combo Enable/Disable Toggle — Toggle combos directly from the dashboard
• Manual Combo Ordering — Drag combo cards by handle and persist the order in SQLite
• Provider Toggle — Enable/disable all connections for a provider with one click
• Blocked Providers — Exclude specific providers from /v1/models listing

Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.

How OmniRoute solves it:

• MCP appears in the dashboard navigation and endpoint protocol tab
• Dedicated MCP management page with process, tools, scopes, and audit
• Built-in quick-start for omniroute --mcp and client onboarding

Agent workflows need both direct replies and long-running streamed execution with lifecycle control.

How OmniRoute solves it:

• A2A JSON-RPC endpoint (POST /a2a) with message/send and message/stream
• SSE streaming with terminal state propagation
• Task lifecycle APIs for tasks/get and tasks/cancel

Operational teams need to know if MCP is actually alive, not just whether an API is reachable.

How OmniRoute solves it:

• Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode
• MCP status API combining heartbeat + recent activity
• UI status cards for process/uptime/heartbeat freshness

When tools mutate config or trigger ops actions, teams need forensic traceability.

How OmniRoute solves it:

• SQLite-backed audit logging for MCP tool calls
• Filters by tool, success/failure, API key, and pagination
• Dashboard audit table + stats endpoints for automation

Different clients should have least-privilege access to tool categories.

How OmniRoute solves it:

• 10 granular MCP scopes for controlled tool access
• Scope enforcement and visibility in MCP management UI
• Safe default posture for operational tooling

Teams need quick runtime changes during incidents or cost events.

How OmniRoute solves it:

• Switch combo activation directly from MCP dashboard
• Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page
• Review live provider breaker state from the Health dashboard

Without lifecycle visibility, task incidents become hard to triage.

How OmniRoute solves it:

• Task listing/filtering by state/skill with pagination
• Drill-down on task metadata, events, and artifacts
• Task cancellation endpoint and UI action with confirmation

Streaming workflows require operational insight into concurrency and live connections.

How OmniRoute solves it:

• Active stream counters integrated into A2A status
• Last task timestamp and per-state counts
• A2A dashboard cards for real-time ops monitoring

External clients and orchestrators need machine-readable metadata for onboarding.

How OmniRoute solves it:

• Agent Card exposed at /.well-known/agent.json
• Capabilities and skills shown in management UI
• A2A status API includes discovery metadata for automation

If users cannot discover protocol surfaces, adoption and support quality drop.

How OmniRoute solves it:

• Consolidated Endpoints page with tabs for Proxy, MCP, A2A, and API Endpoints
• Inline service status toggles (Online/Offline) for MCP and A2A
• Links from overview to dedicated management tabs

Mock tests are not enough to validate protocol compatibility before release.

How OmniRoute solves it:

• E2E suite that boots app and uses real MCP SDK client transport
• A2A client tests for discovery, send, stream, get, and cancel flows
• Cross-check assertions against MCP audit and A2A tasks APIs

Splitting observability by protocol creates blind spots and longer MTTR.

How OmniRoute solves it:

• Unified dashboards/logs/analytics in one product
• Health + audit + request telemetry across OpenAI, MCP, and A2A layers
• Operational APIs for status and automation

Running many separate services increases operational cost and failure modes.

How OmniRoute solves it:

• OpenAI-compatible proxy, MCP server, and A2A server in one stack
• Shared auth, resilience, data store, and observability
• Consistent policy model across all interaction surfaces

Teams lose velocity when stitching multiple ad-hoc services and scripts.

How OmniRoute solves it:

• Unified endpoint strategy for clients and agents
• Built-in protocol management UIs and smoke validation paths
• Production-ready foundations (security, logging, resilience, backup)

During deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.

How OmniRoute solves it:

• Proactive Context Compression — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.
• Structural Integrity Guards — Automatically tracks explicit tool_use definitions and ensures that if a tool input is truncated, its corresponding tool_result is also safely removed, preventing API validation errors.
• Multi-Layer Dropping — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.

For Void Linux users, you can build a native package using xbps-src. Save this block as srcpkgs/omniroute/template:

# Template file for 'omniroute'
pkgname=omniroute
version=3.4.1
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Universal AI gateway with smart routing for multiple LLM providers"
maintainer="zenobit <zenobit@disroot.org>"
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false

do_build() {
	# Determine target CPU arch for node-gyp
	local _gyp_arch
	case "$XBPS_TARGET_MACHINE" in
		aarch64*) _gyp_arch=arm64 ;;
		armv7*|armv6*) _gyp_arch=arm ;;
		i686*) _gyp_arch=ia32 ;;
		*) _gyp_arch=x64 ;;
	esac

	# 1) Install all deps – skip scripts (no network in do_build, native modules
	#    compiled separately below; better-sqlite3 is serverExternalPackage so
	#    Next.js does not execute it during next build)
	NODE_ENV=development npm ci --ignore-scripts

	# 2) Build the Next.js standalone bundle
	npm run build

	# 3) Copy static assets into standalone
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) Compile better-sqlite3 native binding for the target architecture.
	#    Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used
	#    without npm altering them.
	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")

	# 5) Place the compiled binding into the standalone bundle
	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
	mkdir -p "$_bs3_release"
	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"

	# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true
	#    so sharp is not used at runtime; x64 .so files would break aarch64 strip
	rm -rf .next/standalone/node_modules/@img

	# 7) Copy pino runtime deps omitted by Next.js static analysis:
	#    pino-abstract-transport – required by pino's worker thread
	#    split2 – dep of pino-abstract-transport
	#    process-warning – dep of pino itself
	for _mod in pino-abstract-transport split2 process-warning; do
		cp -r "node_modules/$_mod" .next/standalone/node_modules/
	done
}

do_check() {
	npm run test:unit
}

do_install() {
	vmkdir usr/lib/omniroute/.next

	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone

	# Prevent removal of empty Next.js app router dirs by the post-install hook
	for _d in \
		.next/standalone/.next/server/app/dashboard \
		.next/standalone/.next/server/app/dashboard/settings \
		.next/standalone/.next/server/app/dashboard/providers; do
		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
	done

	cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
	vbin "${WRKDIR}/omniroute"
}

post_install() {
	vlicense LICENSE
}

Start MCP transport in stdio mode:

omniroute --mcp

Recommended validation flow:

1. Connect your MCP client over stdio.
2. Run omniroute_get_health.
3. Run omniroute_list_combos.
4. Open /dashboard/mcp to confirm heartbeat, activity, and audit.

Useful APIs for automation:

• GET /api/mcp/status
• GET /api/mcp/tools
• GET /api/mcp/audit
• GET /api/mcp/audit/stats

Discover the agent:

curl http://localhost:20128/.well-known/agent.json

Send a task:

curl -X POST http://localhost:20128/a2a \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}'

Manage lifecycle:

• GET /api/a2a/status
• GET /api/a2a/tasks
• GET /api/a2a/tasks/:id
• POST /api/a2a/tasks/:id/cancel

Operational UI:

• /dashboard/a2a for task/state/stream observability and smoke actions

Validate both protocols with real clients:

npm run test:protocols:e2e

This verifies:

• MCP SDK client connect/list/call
• A2A discovery/send/stream/get/cancel
• Cross-check data in MCP audit and A2A task management APIs

Claude Code (Pro/Max)

Dashboard → Providers → Connect Claude Code
→ OAuth login → Auto token refresh
→ 5-hour + weekly quota tracking

Models:
  cc/claude-opus-4-7
  cc/claude-sonnet-4-5-20250929
  cc/claude-haiku-4-5-20251001

Pro Tip: Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!

OpenAI Codex (Plus/Pro)

Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset

Models:
  cx/gpt-5.2-codex
  cx/gpt-5.1-codex-max

Codex Account Limit Management (5h + Weekly)

Each Codex account now has policy toggles in Dashboard -> Providers:

• 5h (ON/OFF): enforce the 5-hour window threshold policy.
• Weekly (ON/OFF): enforce the weekly window threshold policy.
• Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.
• Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.
• Reset behavior: when the provider resetAt time passes, the account becomes eligible again automatically.

Scenarios:

• 5h ON + Weekly ON: account is skipped when either window reaches threshold.
• 5h OFF + Weekly ON: only weekly usage can block the account.
• 5h ON + Weekly OFF: only 5-hour usage can block the account.
• resetAt passed: account re-enters rotation automatically (no manual re-enable).

GitHub Copilot

Dashboard → Providers → Connect GitHub
→ OAuth via GitHub
→ Monthly reset (1st of month)

Models:
  gh/gpt-5
  gh/claude-4.5-sonnet
  gh/gemini-3.1-pro-preview

NVIDIA NIM (FREE developer access — 70+ models)

1. Sign up: build.nvidia.com
2. Get free API key (1000 inference credits included)
3. Dashboard → Add Provider → NVIDIA NIM:
   • API Key: nvapi-your-key

Models: nvidia/llama-3.3-70b-instruct, nvidia/mistral-7b-instruct, and 50+ more

Pro Tip: OpenAI-compatible API — works seamlessly with OmniRoute's format translation!

DeepSeek

1. Sign up: platform.deepseek.com
2. Get API key
3. Dashboard → Add Provider → DeepSeek

Models: deepseek/deepseek-chat, deepseek/deepseek-coder

Groq (Free Tier Available!)

1. Sign up: console.groq.com
2. Get API key (free tier included)
3. Dashboard → Add Provider → Groq

Models: groq/llama-3.3-70b, groq/mixtral-8x7b

Pro Tip: Ultra-fast inference — best for real-time coding!

OpenRouter (100+ Models)

1. Sign up: openrouter.ai
2. Get API key
3. Dashboard → Add Provider → OpenRouter

Models: Access 100+ models from all major providers through a single API key.

Dashboard behavior: OpenRouter models are managed from Available Models. Manual add, import, and auto-sync all update the same list.

GLM-4.7 (Daily reset, $0.6/1M)

1. Sign up: Zhipu AI
2. Get API key from Coding Plan
3. Dashboard → Add API Key:
   • Provider: glm
   • API Key: your-key

Use: glm/glm-4.7

Pro Tip: Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.

MiniMax M2.1 (5h reset, $0.20/1M)

1. Sign up: MiniMax
2. Get API key
3. Dashboard → Add API Key

Use: minimax/MiniMax-M2.1

Pro Tip: Cheapest option for long context (1M tokens)!

Kimi K2 ($9/month flat)

1. Subscribe: Moonshot AI
2. Get API key
3. Dashboard → Add API Key

Use: kimi/kimi-latest

Pro Tip: Fixed $9/month for 10M tokens = $0.90/1M effective cost!

Qoder (5 FREE models via OAuth)

Dashboard → Connect Qoder
→ Qoder OAuth login
→ Unlimited usage

Models:
  if/kimi-k2-thinking
  if/qwen3-coder-plus
  if/glm-4.7
  if/minimax-m2
  if/deepseek-r1

Qwen (4 FREE models via Device Code)

Dashboard → Connect Qwen
→ Device code authorization
→ Unlimited usage

Models:
  qw/qwen3-coder-plus
  qw/qwen3-coder-flash

Kiro (Claude FREE)

Dashboard → Connect Kiro
→ AWS Builder ID or Google/GitHub
→ Unlimited usage

Models:
  kr/claude-sonnet-4.5
  kr/claude-haiku-4.5

Example 1: Maximize Subscription → Cheap Backup

Dashboard → Combos → Create New

Name: premium-coding
Models:
  1. cc/claude-opus-4-7 (Subscription primary)
  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
  3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)

Use in CLI: premium-coding

Example 2: Free-Only (Zero Cost)

Name: free-combo
Models:
  1. if/kimi-k2-thinking (unlimited)
  2. qw/qwen3-coder-plus (unlimited)

Cost: $0 forever!

Cursor IDE

Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [from OmniRoute dashboard]
  Model: cc/claude-opus-4-7

Claude Code

Use the CLI Tools page in the dashboard for one-click configuration, or edit ~/.claude/settings.json manually.

Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"

codex "your prompt"

OpenClaw

Option 1 — Dashboard (recommended):

Dashboard → CLI Tools → OpenClaw → Select Model → Apply

Option 2 — Manual: Edit ~/.openclaw/openclaw.json:

{
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://127.0.0.1:20128/v1",
        "apiKey": "sk_omniroute",
        "api": "openai-completions"
      }
    }
  }
}

Note: OpenClaw only works with local OmniRoute. Use 127.0.0.1 instead of localhost to avoid IPv6 resolution issues.

Cline / Continue / RooCode

Settings → API Configuration:
  Provider: OpenAI Compatible
  Base URL: http://localhost:20128/v1
  API Key: [from OmniRoute dashboard]
  Model: if/kimi-k2-thinking

OpenCode

Step 1: Add OmniRoute as a custom provider:

opencode
/connect
# Select "Other" → Enter ID: "omniroute" → Enter your OmniRoute API key

Step 2: Create/edit opencode.json in your project root:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1"
      },
      "models": {
        "cc/claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
        "gg/gemini-2.5-pro": { "name": "Gemini 2.5 Pro" },
        "if/kimi-k2-thinking": { "name": "Kimi K2 (Free)" }
      }
    }
  }
}

Step 3: Select the model in OpenCode:

/models
# Select any OmniRoute model from the list

Tip: Add any model available in your OmniRoute /v1/models endpoint to the models section. Use the format provider/model-id from your OmniRoute dashboard.

"Language model did not provide messages"

• Provider quota exhausted → Check dashboard quota tracker
• Solution: Use combo fallback or switch to cheaper tier

Rate limiting

• Subscription quota out → Fallback to GLM/MiniMax
• Add combo: cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking

OAuth token expired

• Auto-refreshed by OmniRoute
• If issues persist: Dashboard → Provider → Reconnect

High costs

• Check usage stats in Dashboard → Costs
• Switch primary model to GLM/MiniMax

Dashboard/API ports are wrong

• PORT is the canonical base port (and API port by default)
• API_PORT overrides only OpenAI-compatible API listener
• DASHBOARD_PORT overrides only dashboard/Next.js listener
• Set NEXT_PUBLIC_BASE_URL to your dashboard/public URL (for OAuth callbacks)

Cloud sync errors

• Verify BASE_URL points to your running instance
• Verify CLOUD_URL points to your expected cloud endpoint
• Keep NEXT_PUBLIC_* values aligned with server-side values

First login not working

• Check INITIAL_PASSWORD in .env
• If unset, fallback password is 123456

No request logs

• call_logs in SQLite stores summary metadata for the Request Logs table and analytics views
• Detailed request/response payloads are written to DATA_DIR/call_logs/ as one JSON artifact per request
• Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads
• Export Logs reads the artifact files on demand, while Export All includes the call_logs/ directory alongside storage.sqlite
• Set APP_LOG_TO_FILE=true if you also want application console logs in logs/application/app.log
• Adjust APP_LOG_MAX_FILE_SIZE, APP_LOG_RETENTION_DAYS, APP_LOG_MAX_FILES, and CALL_LOG_MAX_ENTRIES as needed

Connection test shows "Invalid" for OpenAI-compatible providers

• Many providers don't expose a /models endpoint
• OmniRoute v1.0.6+ includes fallback validation via chat completions
• Ensure base URL includes /v1 suffix

🔐 OAuth on a Remote Server

⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server

The OAuth credentials bundled in OmniRoute are registered for localhost only. When you access OmniRoute on a remote server (e.g. https://omniroute.myserver.com), Google rejects the authentication with:

Error 400: redirect_uri_mismatch

Solution: Configure your own OAuth credentials

You need to create an OAuth 2.0 Client ID in Google Cloud Console with your server's URI.

Step-by-step

1. Open Google Cloud Console

Go to: https://console.cloud.google.com/apis/credentials

2. Create a new OAuth 2.0 Client ID

• Click "+ Create Credentials" → "OAuth client ID"
• Application type: "Web application"
• Name: anything you like (e.g. OmniRoute Remote)

3. Add Authorized Redirect URIs

In the "Authorized redirect URIs" field, add:

https://your-server.com/callback

Replace your-server.com with your server's domain or IP (include the port if needed, e.g. http://45.33.32.156:20128/callback).

4. Save and copy the credentials

After creating, Google will show the Client ID and Client Secret.

5. Set environment variables

In your .env (or Docker environment variables):

# For Antigravity:
ANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret

GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret

6. Restart OmniRoute

# npm:
npm run dev

# Docker:
docker restart omniroute

7. Try connecting again

Google will now redirect correctly to https://your-server.com/callback.

Temporary workaround (without custom credentials)

If you don't want to set up your own credentials right now, you can still use the manual URL flow:

1. OmniRoute opens the Google authorization URL
2. After authorizing, Google tries to redirect to localhost (which fails on the remote server)
3. Copy the full URL from your browser's address bar (even if the page doesn't load)
4. Paste that URL into the field shown in the OmniRoute connection modal
5. Click "Connect"

This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.

Error 400: redirect_uri_mismatch

https://seu-servidor.com/callback

# Para Antigravity:
ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com
ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret

GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com
GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret

# Se usando npm:
npm run dev

# Se usando Docker:
docker restart omniroute

• Runtime: Node.js 18–22 LTS (⚠️ Node.js 24+ is not supported — better-sqlite3 native binaries are incompatible)
• Language: TypeScript 5.9 — 100% TypeScript across src/ and open-sse/ (zero any in core modules since v2.0)
• Framework: Next.js 16 + React 19 + Tailwind CSS 4
• Database: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills
• Schemas: Zod (MCP tool I/O validation, API contracts)
• Protocols: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)
• Streaming: Server-Sent Events (SSE)
• Auth: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization
• Testing: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)
• CI/CD: GitHub Actions (auto npm publish + Docker Hub on release)
• Website: omniroute.online
• Package: npmjs.com/package/omniroute
• Docker: hub.docker.com/r/diegosouzapw/omniroute
• Resilience: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing