OmniRoute Guide: AI Gateway Routing, Setup and Risks

OmniRoute puts one local gateway between a coding tool and many AI providers. Its catalog is only one part of the product. The surrounding control plane handles protocol translation, account selection, model combinations, quota-aware fallback, health tracking, and inspection through a dashboard.

That convenience also creates a concentrated trust boundary. The gateway can hold provider credentials, observe prompts and responses, rewrite payloads, and—in optional modes—inspect encrypted traffic. This guide explains both sides: how OmniRoute works and how to evaluate it without treating a long feature list as proof of production readiness.

What OmniRoute is

OmniRoute is an MIT-licensed, self-hosted AI gateway written primarily in TypeScript and built around a Next.js dashboard plus shared routing services. Its documented API surfaces include:

• OpenAI-compatible endpoints under /v1, including chat completions, responses, embeddings, reranking, image, audio, video, search, and moderation routes;
• an Anthropic-compatible messages surface for clients such as Claude Code;
• a Gemini-compatible surface under /v1beta;
• MCP and A2A servers that expose gateway operations to agents;
• local provider, key, alias, combo, usage, cost, and settings state backed mainly by SQLite.

The official website describes hundreds of integrations and more than 90 free options. Those are catalog claims, not hundreds of services operated by OmniRoute. You still supply an upstream account, OAuth session, API key, subscription, or local model runtime. Each upstream's limits, billing rules, regional availability, and terms continue to apply.

If you only need a smaller local router, compare the narrower 9Router deep dive. OmniRoute trades a larger operational and security surface for broader routing and observability features.

How the request path works

A normal OpenAI-compatible request follows this conceptual path:

Coding tool or SDK
  → authenticated OmniRoute endpoint
  → request validation and optional guardrails
  → model alias / auto route / saved combo resolution
  → provider and account selection
  → provider-specific payload translation
  → upstream API or local runtime
  → streamed response normalization
  → usage, cost, health, and audit records

The architecture documentation separates the Next.js API routes from a shared SSE/routing core in src/sse/* and open-sse/*. That core handles provider execution, translation, streaming, fallback, and usage accounting. This matters when debugging: a client may speak OpenAI format while the selected upstream expects Anthropic, Gemini, or a provider-specific dialect.

Three details are easy to miss:

1. Model IDs carry routing meaning. A provider/model ID, alias, combo name, or auto/* route may take a different resolution path.
2. The selected account can change independently of the provider. Multiple credentials for one provider can be evaluated for cooldown, quota, or health.
3. Normalization is active behavior. Role changes, reasoning fields, tool schemas, structured output, and streaming events may be rewritten for compatibility.

That makes OmniRoute useful as an adapter, but it also means “drop-in compatible” should be tested with your exact client, model, tools, and streaming behavior—not inferred from a successful /v1/models call.

Routing and resilience

OmniRoute supports persisted model combinations and zero-configuration virtual routes such as:

The auto-combo documentation describes a weighted score built from health, quota headroom, cost, latency, task fit, stability, account tier, model fit, context needs, and connection density. Some signals depend on telemetry or optional external model data; when those inputs are absent, the decision can fall back to static or partial information.

Routing is only one layer. The resilience guide distinguishes three failure scopes:

• A provider circuit breaker stops traffic to a provider after repeated service-level failures.
• A connection cooldown skips one rate-limited or unhealthy account while other accounts remain eligible.
• A model lockout can isolate one provider–connection–model combination. The documented default leaves this feature disabled until configured.

This separation is sensible: one model returning 404 should not disable every key for the provider. But several paths are deliberately fail-open. Auto-candidate filtering, some concurrency controls, and guardrail execution favor continuing a request when their own lookup or hook fails. Decide whether availability-first behavior matches your environment.

Constrained local evaluation

As of this review, npm reported 3.8.48 as the latest stable package while the repository's release branch identified itself as 3.8.49. Neither snapshot contains the still-open ACP route fix in PR #7966. The safest option is to wait for a published release containing that fix and verify its release notes. The commands below are only for a disposable, loopback-only evaluation without production credentials.

The stable package declares Node >=22 <23 or >=24 <27. The reviewed source branch raises the Node 22 floor to 22.22.2.

node --version
npm install -g [email protected] --include=optional
omniroute --output json doctor --no-liveness
OMNIROUTE_SERVER_HOST=127.0.0.1 REQUIRE_API_KEY=true omniroute --no-open

The 3.8.48 server otherwise defaults to 0.0.0.0; --no-open only suppresses the browser launch. Confirm the listening address with an OS networking tool before adding credentials. Once the server is running, execute omniroute --output json doctor in a second terminal to include the health probe.

OmniRoute's setup guide uses port 20128 by default. Keep the first run on loopback and open the local dashboard on that port. In the dashboard:

1. Create a strong management password and keep management login required.
2. Add one low-risk test provider rather than every personal account.
3. Enable REQUIRE_API_KEY, which is false by default for local use, then create a separate endpoint key for the client.
4. Start with one explicit provider/model route.
5. Inspect logs, cost records, and health behavior before enabling automatic fallback.

The package includes native optional dependencies such as SQLite and OS-keyring bindings. The official updater explicitly preserves optional dependencies; if diagnostics report a missing native feature after installation, repair the package before trusting persistence or credential handling.

Connect a coding tool

The common OpenAI-compatible configuration is:

Base URL: http://127.0.0.1:20128/v1
API key:  an endpoint key created in OmniRoute
Model:    an explicit provider/model ID for the first test

Check discovery without exposing the key in command history:

export OMNIROUTE_API_KEY='replace-with-a-test-endpoint-key'
curl -fsS http://127.0.0.1:20128/v1/models \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY"

# After enabling REQUIRE_API_KEY, an unauthenticated request should return 401.
curl -i http://127.0.0.1:20128/v1/models

OmniRoute also documents tool-specific setup commands:

omniroute setup-codex --dry-run
omniroute setup-claude --dry-run
omniroute setup-opencode --dry-run
omniroute setup-continue --dry-run

Use --dry-run first because these commands may write into a tool's configuration directory. Neither launcher writes persistent configuration: omniroute launch injects Claude Code's ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN environment variables, while omniroute launch-codex supplies the OmniRoute provider through Codex -c configuration flags.

Base URL conventions differ by client. Some tools expect the root URL and append /v1/chat/completions; others require a URL already ending in /v1. Follow the official CLI integration matrix instead of guessing.

After explicit routing works, compare auto/coding or a small persisted combo against the same fixed prompt. Record response quality, p95 latency, fallback events, and billed tokens. For broader quota planning, the Antigravity fallback workflow shows why a fallback chain should be intentional rather than an unbounded list of accounts.

Security and privacy boundaries

A gateway that centralizes credentials and prompts deserves the same scrutiny as an internal control plane.

Credentials and local state

Review where your installation stores its database, key material, logs, exports, and backups. The architecture notes say request logging can include full headers and bodies when enabled; that directory is sensitive even if provider credentials are encrypted elsewhere. Limit filesystem permissions and backup access, and test account revocation.

Endpoint and management authentication

An endpoint key protects model traffic only when REQUIRE_API_KEY=true; that flag defaults to false for local use. Management routes can also bypass login when requireLogin=false. Keep both protections enabled, then treat them as additions to—not substitutes for—TLS and network controls. Rotate test keys and verify that model, dashboard, and management routes reject anonymous requests.

Guardrails are configurable and fail-open

Built-in guardrails cover PII masking, prompt-injection detection, and a vision bridge. Their behavior depends on settings. Prompt-injection detection defaults to warning rather than blocking, and the registry continues when a guardrail throws. That is observability—not a universal security boundary. Test the configured mode and monitor failures.

Stealth and traffic interception are high-risk options

OmniRoute documents request fingerprinting, TLS impersonation, payload obfuscation, proxy support, and optional MITM traffic-capture modes. Its own guide says these features are for compatibility with user-owned accounts, not for fraud, credential sharing, or Terms-of-Service evasion.

The Linux TPROXY decrypt mode is especially privileged: it requires CAP_NET_ADMIN or root, installs a trusted certificate authority, and can decrypt arbitrary intercepted HTTPS destinations. It is disabled by default. Leave it off unless you have a controlled debugging need, a dedicated machine, and a tested cleanup procedure.

Some provider modes can also raise account-ban or unexpected-spend risk. Check the upstream terms for proxying, automation, account sharing, and OAuth use. “Works technically” does not mean “permitted contractually.”

Optional sync changes the data boundary

The core product is local, but the architecture lists optional cloud sync. If enabled, identify the remote service, fields synchronized, retention policy, and revocation path. Keep it disabled until those answers match your requirements.

Claims that need context

OmniRoute's official pages make ambitious claims. They are useful leads, but they do not all carry the same evidentiary weight.

The project's free-tier documentation is more careful than its headline: it separates recurring grants, signup credits, uncapped free services, deposit-unlocked quotas, and theoretical ceilings. Use that methodology, but recheck each upstream's official terms and current quota before budgeting.

A practical compression test uses a representative prompt corpus:

1. Run uncompressed requests against a fixed model.
2. Enable one compression path at a time.
3. Compare input tokens, output quality, tool-call correctness, latency, and cost.
4. Repeat with long code, logs, structured data, and multilingual text.
5. Keep compression off for workloads where an omitted detail is more expensive than extra tokens.

Maintenance and current caveats

OmniRoute shows active development, frequent releases, a large contributor surface, and broad automated checks. That pace is a strength and a source of integration risk.

At the July 21 review point:

• npm stable was 3.8.48, while release-branch documentation was already on 3.8.49;
• PR #7952 proposed transitive dependency fixes for release/v3.8.49 and remained open with green checks; its open main companion, PR #7953, still had quality-ratchet failures;
• issue #7976 documented an OpenCode plugin bug where saved combo IDs could be double-prefixed, while direct OmniRoute requests and ordinary models still worked;
• PR #7966 confirmed that /api/acp/agents was a spawn-capable route missing the loopback gate. The maintainer's analysis says exploitation requires valid auth, or login disabled, and proposes adding the route to LOCAL_ONLY_API_PREFIXES; the fix remained open and absent from both reviewed snapshots.

These are snapshots, not permanent verdicts. Check the latest release notes, open security advisories, dependency audit, and the issues affecting your chosen integration immediately before installation.

For upgrades, do not follow the release branch blindly. Back up configuration, read the changelog between your installed and target versions, stage the update, run omniroute doctor, then smoke-test model discovery, streaming, tool calls, and fallback before replacing a working instance.

Who should use OmniRoute

OmniRoute is a strong candidate when you need several of these together:

• one local endpoint for multiple coding tools;
• provider and account fallback with a dashboard;
• OpenAI, Anthropic, and Gemini protocol translation;
• quota, cost, latency, and health visibility;
• local models alongside hosted APIs;
• MCP or A2A control surfaces;
• an operator willing to maintain a rapidly changing gateway.

It is a weaker fit when you need a minimal proxy, a fully managed SLA, strict multi-tenant isolation without additional engineering, or a gateway whose privileged inspection and compatibility features are absent by design. A simpler router or a direct SDK integration may be easier to audit.

Provider support alone is not enough. OmniRoute is a good fit only when its routing and observability benefits justify concentrating that much authority in one service.

Evaluation checklist

Use this before moving beyond a local test:

• [ ] Pin a stable version and record the package checksum or lockfile.
• [ ] Verify the MIT license and release provenance.
• [ ] Run diagnostics and confirm optional native dependencies loaded.
• [ ] Bind to loopback for the first evaluation.
• [ ] Create separate management and endpoint credentials.
• [ ] Connect a low-risk test account before personal or production accounts.
• [ ] Confirm model listing, streaming, tools, structured output, and error translation.
• [ ] Test an explicit route before auto/* or a large combo.
• [ ] Force rate-limit and provider-failure scenarios; inspect breaker and cooldown behavior.
• [ ] Measure compression on your own prompts instead of adopting the advertised range.
• [ ] Review full-body logging, backups, cloud sync, MCP/A2A, and custom-agent permissions.
• [ ] Leave stealth, MITM, TPROXY, and root-level capture disabled unless specifically required.
• [ ] Check current dependency/security status and integration-specific issues.
• [ ] Add TLS, network restrictions, monitoring, and a rollback plan before remote exposure.

OmniRoute's main achievement is assembling routing, translation, resilience, accounting, and agent-facing controls into one local interface. Its main risk is the same concentration. Evaluate the control plane as carefully as the models behind it.