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

> Learn to add a custom provider to OmniRoute registry with this step-by-step guide. Follow clear instructions to define your provider and validate schema using npm run typecheck:core. Integrate with ease!

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-21

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/noauth.ts) for providers requiring no credentials
- **OAuth** – [`src/shared/constants/providers/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/web-cookie.ts) for session‑cookie providers (e.g., Google Search)
- **Local / Self‑hosted** – [`src/shared/constants/providers/local.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts) (lines 5‑219):

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts) (lines 13‑22) imports all category files and merges them into the exported `AI_PROVIDERS` proxy:

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/providers.ts) (lines 32‑43), the system validates every section using `validateProviders`:

```typescript
// 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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/apikey/index.ts) (lines 1‑120):

```typescript
// 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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.