How to Add a Custom Provider to the OmniRoute Provider Registry

Adding a custom provider to the OmniRoute provider registry requires selecting the appropriate authentication category, inserting a provider definition object into the corresponding constants file under src/shared/constants/providers/, and running the Zod validation suite to ensure schema compliance.

OmniRoute unifies LLM providers under a single routing system that powers UI listings, API validation, and request handling. To extend the platform with a new service, you must register your provider in the centralized registry located in src/shared/constants/providers/. This guide walks through the exact file paths, required schema fields, and validation steps needed to add a custom provider to the OmniRoute provider registry without breaking existing functionality.

Choose the Authentication Category

OmniRoute organizes providers by authentication method. You must select the correct category before inserting your definition.

• No-auth: Providers requiring no credentials (e.g., free open-source models). File: src/shared/constants/providers/noauth.ts
• OAuth: Providers using OAuth flows (e.g., Anthropic, GitHub Copilot). File: src/shared/constants/providers/oauth.ts
• API-key: Bearer-style key authentication. File: src/shared/constants/providers/apikey/index.ts
• Web-cookie: Session-based providers (e.g., Google Search). File: src/shared/constants/providers/web-cookie.ts
• Local/Self-hosted: Self-hosted model servers (e.g., Ollama, LM Studio). File: src/shared/constants/providers/local.ts

Most third-party LLM services use either OAuth or API-key authentication.

Insert the Provider Definition

Open the file matching your selected category and insert a new object literal into the exported constants object.

Required Schema Fields

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

Field	Description
id	Unique stable identifier used throughout the system
name	Human-readable display name
icon	Icon name from the built-in UI library
color	Brand hex color code
subscriptionRisk	Boolean indicating if paid subscription is required
riskNoticeVariant	One of: oauth, webCookie, deprecated, embedded-service

Optional fields include alias (short CLI name), authHint (UI help text), hasFree (free tier indicator), and website.

Example: OAuth Provider Definition

// src/shared/constants/providers/oauth.ts (lines 5-219)
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,
  },
};

Automatic Registration via Global Registry

You do not need to manually import new entries. The global registry 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 { APIKEY_PROVIDERS } from "./providers/apikey";
import { WEB_COOKIE_PROVIDERS } from "./providers/web-cookie";
import { LOCAL_PROVIDERS } from "./providers/local";
// ... additional imports

export const AI_PROVIDERS = {
  ...NOAUTH_PROVIDERS,
  ...OAUTH_PROVIDERS,
  ...APIKEY_PROVIDERS,
  // ... merged categories
};

Because the aggregator merges entire category objects, your new entry becomes immediately available system-wide upon saving the file.

Validate the Provider Configuration

The codebase validates every provider category against the Zod schema at the bottom of src/shared/constants/providers.ts (lines 32-43):

import { validateProviders } from "../validation/providerSchema";

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

Run the validation suite to verify your configuration:

npm run typecheck:core

# Or complete verification:

npm run lint && npm run test

If fields fail validation, the Zod schema will output specific error messages indicating the offending property.

Implement Custom Request Handling (Optional)

OpenAI-compatible providers work automatically with the default executor at open-sse/executors/default.ts. For non-standard APIs, you must:

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

See docs/frameworks/EXECUTORS.md in the repository for detailed implementation guidelines.

Complete Example: Adding an API-Key Provider

Below is a complete implementation for an imaginary FastAI provider using API-key authentication:

// src/shared/constants/providers/apikey/index.ts (lines 1-120)
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 this change, run the validation commands. Upon successful completion, the provider appears in the "Add Provider" dropdown, becomes selectable in the UI, and integrates with the routing engine.

Summary

• Select the authentication category that matches your provider's credential requirements (OAuth, API-key, No-auth, etc.)
• Insert the provider definition into the appropriate file under src/shared/constants/providers/, ensuring all required schema fields are present
• Run Zod validation using npm run typecheck:core to confirm schema compliance before deployment
• (Optional) Implement custom executors in open-sse/executors/ for non-OpenAI-compatible request formats

Frequently Asked Questions

What fields are required when adding a provider to the OmniRoute registry?

The Zod schema requires six fields: id (unique identifier), name (display name), icon (UI library reference), color (brand hex), subscriptionRisk (boolean for paid tiers), and riskNoticeVariant (one of four authentication variants). Optional fields like alias, authHint, and hasFree enhance CLI and UI usability but are not mandatory.

How does the global registry recognize my new provider?

The global registry at src/shared/constants/providers.ts imports entire category files (lines 13-22) and merges them into the exported AI_PROVIDERS proxy. Because it imports the constant objects by reference, any new entry added to src/shared/constants/providers/oauth.ts or similar files automatically appears in the system without manual registration.

Where is the validation logic defined for provider schemas?

Validation occurs in src/shared/validation/providerSchema.ts using the validateProviders() function. This Zod-based validator checks each provider object against strict type definitions and runs at the bottom of src/shared/constants/providers.ts (lines 32-43) for every authentication category.

Do I need custom code for API request handling?

Only if your provider deviates from the OpenAI API format. Standard OpenAI-compatible providers use the default executor at open-sse/executors/default.ts. For custom request shapes, create a new executor in open-sse/executors/ and register it in open-sse/executors/index.ts, optionally adding a translator in open-sse/translator/ for payload transformation.

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