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

To add a custom provider to the OmniRoute provider registry, choose the correct authentication category file in src/shared/constants/providers/, insert a provider definition object that satisfies the Zod schema requirements, and run the validation suite to automatically include it in the global AI_PROVIDERS registry.

OmniRoute consolidates LLM providers into a unified routing system through a centralized registry located in src/shared/constants/providers.ts. Adding a custom provider involves defining metadata in the appropriate category file and relying on the built-in validation system to ensure compatibility with the routing engine and UI components.

Step 1: Select the Authentication Category

OmniRoute organizes providers by authentication method. You must add your custom provider to the correct category file to ensure proper credential handling and UI rendering.

Choose from the following authentication categories:

Category	File Path	Use Case
No‑auth	src/shared/constants/providers/noauth.ts	Providers requiring no credentials (free open‑source models).
OAuth	src/shared/constants/providers/oauth.ts	Services using OAuth flows (e.g., Anthropic, GitHub Copilot).
API‑key	src/shared/constants/providers/apikey/index.ts	Services requiring bearer‑style API keys.
Web‑cookie	src/shared/constants/providers/web-cookie.ts	Providers relying on session cookies.
Local / Self‑hosted	src/shared/constants/providers/local.ts	Self‑hosted servers like Ollama or LM‑Studio.

Most third‑party LLM services fall into either OAuth or API‑key categories. Select the file that matches your provider’s authentication mechanism before proceeding.

Step 2: Define the Provider Configuration

Open the selected category file and insert a new provider object literal. The OmniRoute source code validates every entry against a strict Zod schema defined in src/shared/validation/providerSchema.ts.

Required Schema Fields

Every provider definition must include these fields:

Field	Type	Description
id	string	Unique stable identifier used throughout the codebase.
name	string	Human‑readable display name for the UI.
icon	string	Icon name from the built‑in icon library.
color	string	Brand hex color code (e.g., "#123456").
subscriptionRisk	boolean	Set to true if the provider requires a paid subscription.
riskNoticeVariant	string	One of "oauth", "webCookie", "deprecated", or "embedded-service".

Optional Fields

You may also include these optional fields to enhance the UI:

• alias: Short alias for CLI commands (e.g., "exa").
• authHint: Help text displayed in the "Add Provider" dialog.
• hasFree: Boolean indicating whether a free tier exists.
• website, textIcon, deprecated, deprecationReason: Additional metadata fields.

Example: Adding an OAuth Provider

Below is a minimal example for a fictional OAuth provider called ExampleAI added to src/shared/constants/providers/oauth.ts:

// src/shared/constants/providers/oauth.ts
export const OAUTH_PROVIDERS = {
  // Existing providers...
  exampleai: {
    id: "exampleai",
    alias: "exa",
    name: "ExampleAI",
    icon: "smart_toy",
    color: "#123456",
    subscriptionRisk: true,
    riskNoticeVariant: "oauth",
    authHint: "Paste the OAuth token from the ExampleAI dashboard.",
    hasFree: true,
  },
};

Source reference: The OAUTH_PROVIDERS object is defined at lines 5‑219 in the repository.

Step 3: Automatic Registration in the Global Registry

You do not need to manually import new entries into the global registry. The file src/shared/constants/providers.ts automatically aggregates all provider categories through explicit imports (lines 13‑22) 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 aggregator imports entire category objects, your new provider entry becomes automatically visible to the routing engine, UI dropdowns, and API validation layers immediately upon saving the file.

Step 4: Validate the Schema

OmniRoute validates every provider section at runtime using the validateProviders function. The validation logic resides at lines 32‑43 of 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");
// ... additional validations

After adding your provider definition, run the validation suite to ensure schema compliance:

npm run typecheck:core

Alternatively, run the full lint and test suite:

npm run lint && npm run test

If any field violates the Zod schema, the validation command will output a specific error message identifying the offending property and expected type.

Optional: Implement Custom Request Handling

Providers that follow the OpenAI API specification work out‑of‑the‑box with the default executor located at open-sse/executors/default.ts. However, if your custom provider uses a non‑standard request shape or requires custom headers, you must implement additional components:

1. Create a custom executor in open-sse/executors/ that extends BaseExecutor.
2. Register the executor in open-sse/executors/index.ts within the getExecutor() factory function.
3. Add a translator in open-sse/translator/ if the request or response format differs from OpenAI standards.

For detailed implementation guidance, refer to the executor documentation in docs/frameworks/EXECUTORS.md.

Complete Example: Adding an API‑Key Provider

The following example demonstrates adding a fictional API‑key provider called FastAI to src/shared/constants/providers/apikey/index.ts:

// 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,
  },
};

Source reference: The APIKEY_PROVIDERS object definition spans lines 1‑120 in the repository.

After committing this change, run the validation commands. Upon successful completion, FastAI will appear in the "Add Provider" dropdown, become selectable in the UI, and integrate fully with the routing engine.

Key Files Reference

File	Purpose	Location
providers.ts	Central aggregator importing all provider categories and running validation.	src/shared/constants/providers.ts
oauth.ts	OAuth provider definitions and metadata.	src/shared/constants/providers/oauth.ts
apikey/index.ts	API‑key provider definitions.	src/shared/constants/providers/apikey/index.ts
providerSchema.ts	Zod validation schema for provider objects.	src/shared/validation/providerSchema.ts
default.ts	Default executor for OpenAI‑compatible providers.	open-sse/executors/default.ts
executors/index.ts	Factory function selecting the appropriate executor per provider.	open-sse/executors/index.ts

Summary

• Select the correct authentication category by choosing the appropriate file in src/shared/constants/providers/ (OAuth, API‑key, no‑auth, etc.).
• Insert a provider definition containing all required Zod schema fields: id, name, icon, color, subscriptionRisk, and riskNoticeVariant.
• Leverage automatic registration via the imports in src/shared/constants/providers.ts—no manual registry updates required.
• Run schema validation using npm run typecheck:core to ensure compliance with the validateProviders function.
• Implement custom executors only if the provider deviates from OpenAI‑compatible request formats.

Frequently Asked Questions

What happens if I forget to include a required field like riskNoticeVariant?

The Zod validator in src/shared/validation/providerSchema.ts will throw a type error when you run npm run typecheck:core, specifying exactly which property is missing and in which provider category. The build will fail until you provide valid values for all required fields.

Can I add a provider without modifying the core repository files?

No. According to the OmniRoute architecture, all providers must be defined in the src/shared/constants/providers/ directory files. The system does not support external plugin registration; providers must be declared in the source code and validated through the built‑in schema checker.

How do I handle providers that require custom HTTP headers or non‑JSON payloads?

You must create a custom executor class in open-sse/executors/ that extends BaseExecutor, then register it in open-sse/executors/index.ts. If the request or response format differs from OpenAI standards, you should also implement a translator in open-sse/translator/ to normalize the data exchange.

Why does my new provider not appear in the UI immediately after editing the file?

The provider becomes visible only after the TypeScript compilation and validation succeed. Run npm run typecheck:core to verify the schema, then restart the development server or rebuild the application to refresh the AI_PROVIDERS registry that powers the UI dropdowns.

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