How to Add a Custom Provider to OmniRoute Registry: A Step‑by‑Step Guide

To add a custom provider to OmniRoute, choose the correct authentication category file in src/shared/constants/providers/, insert a provider definition object with required fields (id, name, icon, color, subscriptionRisk, riskNoticeVariant), and run npm run typecheck:core to validate against the Zod schema.

OmniRoute is an open‑source LLM routing framework that unifies multiple providers under a single registry powering routing logic, UI listings, and API validation. Understanding how to add a custom provider to OmniRoute registry allows you to extend routing capabilities to proprietary or niche services. This guide references the exact file paths, functions, and validation logic found in the diegosouzapw/OmniRoute repository.

Select the Correct Authentication Category

OmniRoute organizes providers by authentication mechanism. Locate the file that matches your provider’s security model:

• No‑auth – src/shared/constants/providers/noauth.ts for providers requiring no credentials
• OAuth – src/shared/constants/providers/oauth.ts for OAuth flows (e.g., Anthropic, Claude)
• API‑key – src/shared/constants/providers/apikey/*.ts for bearer‑style token authentication
• Web‑cookie – src/shared/constants/providers/web-cookie.ts for session‑cookie providers (e.g., Google Search)
• Local / Self‑hosted – src/shared/constants/providers/local.ts for Ollama or LM‑Studio instances
• Specialized – Additional categories like search, audio‑only, or upstream‑proxy live under src/shared/constants/providers/

Most third‑party LLM services use either the OAuth or API‑key category.

Add the Provider Definition

Open the selected category file and insert a new object literal. The following example adds an OAuth provider to src/shared/constants/providers/oauth.ts (lines 5‑219):

// src/shared/constants/providers/oauth.ts
export const OAUTH_PROVIDERS = {
  // Existing providers …
  exampleai: {
    id: "exampleai",               // Unique identifier used throughout the system
    alias: "exa",                  // Short alias for CLI (optional)
    name: "ExampleAI",             // Human‑readable display name
    icon: "smart_toy",             // Icon name from the built‑in icon set
    color: "#123456",              // Brand hex color
    subscriptionRisk: true,        // Set true if the provider requires payment
    riskNoticeVariant: "oauth",    // One of: "oauth", "webCookie", "deprecated", "embedded-service"
    authHint: "Paste the OAuth token from the ExampleAI dashboard.", // UI hint (optional)
    hasFree: true,                 // Signals a free tier exists (optional)
  },
};

Required Provider Fields

The Zod schema in src/shared/validation/providerSchema.ts enforces the following fields:

Field	Description	Required
id	Stable unique identifier across all categories	✅
name	Display name shown in the UI	✅
icon	Icon name from the UI icon library	✅
color	Brand color as hex string	✅
subscriptionRisk	Boolean indicating potential charges	✅
riskNoticeVariant	One of four variants: oauth, webCookie, deprecated, embedded-service	✅
alias	Short CLI alias	❌
authHint	Helper text in the “Add Provider” dialog	❌
hasFree	Indicates free tier availability	❌

Automatic Registration via the Global Registry

You do not need to manually import new entries. The central aggregator at src/shared/constants/providers.ts (lines 13‑22) imports all category files and merges them into the exported AI_PROVIDERS proxy:

// src/shared/constants/providers.ts
import { NOAUTH_PROVIDERS } from "./providers/noauth";
import { OAUTH_PROVIDERS } from "./providers/oauth";
import { WEB_COOKIE_PROVIDERS } from "./providers/web-cookie";
import { APIKEY_PROVIDERS } from "./providers/apikey";
import { LOCAL_PROVIDERS } from "./providers/local";
import { SEARCH_PROVIDERS } from "./providers/search";
import { AUDIO_ONLY_PROVIDERS } from "./providers/audio";
import { UPSTREAM_PROXY_PROVIDERS } from "./providers/upstream-proxy";
import { CLOUD_AGENT_PROVIDERS } from "./providers/cloud-agent";

Because the file imports the entire category object, your new provider becomes automatically visible to the routing engine and UI once you save the file.

Validate with the Zod Schema

At the bottom of providers.ts (lines 32‑43), the system validates every section using validateProviders:

// src/shared/constants/providers.ts
import { validateProviders } from "../validation/providerSchema";

validateProviders(NOAUTH_PROVIDERS, "NOAUTH_PROVIDERS");
validateProviders(OAUTH_PROVIDERS, "OAUTH_PROVIDERS");
validateProviders(APIKEY_PROVIDERS, "APIKEY_PROVIDERS");
validateProviders(WEB_COOKIE_PROVIDERS, "WEB_COOKIE_PROVIDERS");
// … additional validations

After adding your definition, run the validation command:

npm run typecheck:core

If any field violates the schema, the command outputs a specific error message identifying the offending property.

Handle Non‑Standard APIs with Custom Executors

OpenAI‑compatible providers work out‑of‑the‑box with the default executor located at open-sse/executors/default.ts. If your custom provider uses a non‑standard request shape or requires specialized headers, you must:

1. Create a new executor in open-sse/executors/ that extends BaseExecutor
2. Register the executor in open-sse/executors/index.ts inside the getExecutor() factory function
3. Optionally add a request/response translator in open-sse/translator/ if the payload format differs from OpenAI standards

Refer to docs/frameworks/EXECUTORS.md in the repository for advanced implementation details.

Complete Example: Adding an API‑Key Provider

The following snippet adds a fictional API‑key provider named FastAI to src/shared/constants/providers/apikey/index.ts (lines 1‑120):

// src/shared/constants/providers/apikey/index.ts
export const APIKEY_PROVIDERS = {
  // Existing providers …
  fastai: {
    id: "fastai",
    alias: "fa",
    name: "FastAI",
    icon: "bolt",
    color: "#00A8E8",
    subscriptionRisk: false,
    riskNoticeVariant: "apikey",
    authHint: "Paste your FastAI API key (Bearer token).",
    hasFree: true,
  },
};

After committing the change, run the full validation suite:

npm run lint
npm run typecheck:core
npm run test

If the build succeeds, the provider appears in the “Add Provider” dropdown and is fully routable by the combo engine.

Summary

• Identify the correct authentication category (OAuth, API‑key, no‑auth, etc.) and open the corresponding file under src/shared/constants/providers/
• Insert a provider definition object containing the six required fields: id, name, icon, color, subscriptionRisk, and riskNoticeVariant
• Commit the change; the global AI_PROVIDERS proxy in providers.ts automatically registers the new entry via its category import
• Execute npm run typecheck:core to validate the entry against the Zod schema defined in providerSchema.ts
• Implement a custom executor in open-sse/executors/ only if the provider deviates from the standard OpenAI request format

Frequently Asked Questions

Where is the provider registry defined in OmniRoute?

The central registry lives in src/shared/constants/providers.ts. This file imports all authentication category files (lines 13‑22) and exports the AI_PROVIDERS proxy that aggregates every provider definition into a single routable collection.

What fields are required when adding a new provider?

The Zod schema requires six fields: id (unique string), name (display string), icon (UI icon name), color (hex string), subscriptionRisk (boolean), and riskNoticeVariant (enum string). Optional fields include alias, authHint, hasFree, website, and deprecationReason.

Do I need to manually register my provider in a central list?

No. Because src/shared/constants/providers.ts imports entire category objects (such as OAUTH_PROVIDERS or APIKEY_PROVIDERS), any object you add to those files is automatically included in the global registry without additional imports or registration steps.

How do I fix validation errors when adding a provider?

Run npm run typecheck:core to execute the Zod validation defined in src/shared/validation/providerSchema.ts. The error output specifies exactly which field failed validation and why. Ensure your object includes all required fields and that riskNoticeVariant matches one of the four allowed enum values.

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