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

> Learn to add a custom provider to the OmniRoute provider registry. Follow this step-by-step guide to insert provider definitions and run validation for seamless integration.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/noauth.ts) | Providers requiring no credentials (free open‑source models). |
| **OAuth** | [`src/shared/constants/providers/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts) | Services using OAuth flows (e.g., Anthropic, GitHub Copilot). |
| **API‑key** | [`src/shared/constants/providers/apikey/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/apikey/index.ts) | Services requiring bearer‑style API keys. |
| **Web‑cookie** | [`src/shared/constants/providers/web-cookie.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/web-cookie.ts) | Providers relying on session cookies. |
| **Local / Self‑hosted** | [`src/shared/constants/providers/local.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts):

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

```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 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts):

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

```bash
npm run typecheck:core

```

Alternatively, run the full lint and test suite:

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

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

```

*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`](https://github.com/diegosouzapw/OmniRoute/blob/main/providers.ts) | Central aggregator importing all provider categories and running validation. | [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts) |
| [`oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/oauth.ts) | OAuth provider definitions and metadata. | [`src/shared/constants/providers/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts) |
| [`apikey/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/apikey/index.ts) | API‑key provider definitions. | [`src/shared/constants/providers/apikey/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/apikey/index.ts) |
| [`providerSchema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/providerSchema.ts) | Zod validation schema for provider objects. | [`src/shared/validation/providerSchema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/providerSchema.ts) |
| [`default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/default.ts) | Default executor for OpenAI‑compatible providers. | [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts) |
| [`executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/executors/index.ts) | Factory function selecting the appropriate executor per provider. | [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.