How to Add Custom Providers to OmniRoute's Provider Registry

To add a custom provider to OmniRoute, choose the appropriate authentication category file in src/shared/constants/providers/, insert a provider definition object with required fields like id, name, icon, and color, and run the Zod validation via npm run typecheck:core to ensure schema compliance.

The OmniRoute project (diegosouzapw/OmniRoute) maintains a centralized provider registry that powers its LLM routing engine, UI dropdowns, and API validation. Adding custom providers requires modifying TypeScript constants files and ensuring entries conform to the Zod schema defined in the codebase.

Choose the Authentication Category

OmniRoute organizes providers by authentication method. Select the file that matches your provider's credential requirements:

• No-auth: src/shared/constants/providers/noauth.ts — For providers requiring no credentials (e.g., free open-source models).
• OAuth: src/shared/constants/providers/oauth.ts — For providers using OAuth flows (e.g., Anthropic, Claude).
• API-key: src/shared/constants/providers/apikey/index.ts — For bearer-token style API keys.
• Web-cookie: src/shared/constants/providers/web-cookie.ts — For session-cookie based providers.
• Local / Self-hosted: src/shared/constants/providers/local.ts — For Ollama, LM-Studio, or similar self-hosted servers.

Most third-party LLM services fall under OAuth or API-key categories.

Insert the Provider Definition

Open the selected category file and add a new object literal to the exported constants object. The OAUTH_PROVIDERS definition in src/shared/constants/providers/oauth.ts (lines 5–219) demonstrates the expected pattern:

// 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 and UI (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 paid subscription required
    riskNoticeVariant: "oauth",    // One of: "oauth", "webCookie", "deprecated", "embedded-service"
    authHint: "Paste the OAuth token from the ExampleAI dashboard.", // UI hint text
    hasFree: true,                 // Optional flag indicating free tier availability
  },
};

Required Fields and Schema Validation

The Zod schema in src/shared/validation/providerSchema.ts enforces these required fields:

Field	Description	Required
id	Unique stable identifier across all categories	✅
name	Display name shown in the UI	✅
icon	Icon name from the UI library	✅
color	Brand color in hex format	✅
subscriptionRisk	Boolean indicating potential charges	✅
riskNoticeVariant	Authentication risk category	✅

Optional fields include alias, authHint, hasFree, website, textIcon, and deprecated.

Automatic Registration via Global Registry

You do not need manual imports. The central aggregator at src/shared/constants/providers.ts (lines 13–22) automatically imports all category files:

// 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";
// ... additional imports

These are merged into the exported AI_PROVIDERS proxy, making your new entry immediately available to the routing engine and UI.

Validate Your Changes

After adding the provider definition, run the built-in validation to verify schema compliance. The providers.ts file calls validateProviders() from src/shared/validation/providerSchema.ts for each category (lines 32–43):

npm run typecheck:core

Alternatively, run the full validation suite:

npm run lint && npm run test

If any field violates the Zod schema, the command outputs a specific error indicating the offending property and expected type.

(Optional) Implement Custom Request Handling

Providers with OpenAI-compatible APIs work automatically with the default executor in open-sse/executors/default.ts. For non-standard APIs:

1. Create an executor in open-sse/executors/ extending BaseExecutor.
2. Register it in open-sse/executors/index.ts within the getExecutor() factory function.
3. Add a translator in open-sse/translator/ if request/response formats differ from OpenAI standards.

See docs/frameworks/EXECUTORS.md for detailed implementation guidelines.

Complete Working Example

Below is a complete implementation for an API-key provider named "FastAI" in 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, verify integration:

npm run lint
npm run typecheck:core
npm run test

Upon successful validation, FastAI appears in the "Add Provider" dropdown and becomes selectable in the routing UI.

Summary

• Select the correct authentication category file under src/shared/constants/providers/ based on credential requirements (OAuth, API-key, etc.).
• Insert a provider definition containing required fields (id, name, icon, color, subscriptionRisk, riskNoticeVariant) into the appropriate constants object.
• Commit changes to automatically register the provider via the AI_PROVIDERS proxy in src/shared/constants/providers.ts.
• Run validation using npm run typecheck:core to ensure Zod schema compliance.
• Implement custom executors in open-sse/executors/ only if the provider deviates from OpenAI request formats.

Frequently Asked Questions

What happens if I omit the riskNoticeVariant field?

The Zod schema validation in src/shared/validation/providerSchema.ts will throw a type error when you run npm run typecheck:core. This field is required to categorize the authentication risk for UI warnings, and must be one of the four allowed values: "oauth", "webCookie", "deprecated", or "embedded-service".

Can I add a provider without restarting the application?

Yes. Since OmniRoute uses static imports in src/shared/constants/providers.ts, the provider becomes available immediately after the TypeScript code compiles and the application reloads. For development, hot-reload will pick up changes automatically once validation passes.

Where do I configure custom headers for API requests?

Custom request handling requires implementing a new executor in open-sse/executors/. Extend BaseExecutor and register your implementation in open-sse/executors/index.ts within the getExecutor() factory. If only header transformations are needed, you may also add a translator in open-sse/translator/ without writing a full executor.

How do I verify my provider appears in the UI correctly?

After running npm run typecheck:core successfully, start the development server and navigate to the provider selection dropdown. The name, icon, and color fields you defined should render immediately. Check the browser's developer console for any runtime errors if the icon fails to load.

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