# How to Add Custom Providers to OmniRoute's Provider Registry

> Easily add custom providers to OmniRoute's registry. Follow our guide to define your provider, ensuring schema compliance with Zod validation.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/noauth.ts) — For providers requiring no credentials (e.g., free open-source models).
- **OAuth**: [`src/shared/constants/providers/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts) — For providers using OAuth flows (e.g., Anthropic, Claude).
- **API-key**: [`src/shared/constants/providers/apikey/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/apikey/index.ts) — For bearer-token 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) — For session-cookie based providers.
- **Local / Self-hosted**: [`src/shared/constants/providers/local.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts) (lines 5–219) demonstrates the expected pattern:

```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 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts) (lines 13–22) automatically imports all category files:

```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";
// ... 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/providers.ts) file calls `validateProviders()` from [`src/shared/validation/providerSchema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/providerSchema.ts) for each category (lines 32–43):

```bash
npm run typecheck:core

```

Alternatively, run the full validation suite:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](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 request/response formats differ from OpenAI standards.

See [`docs/frameworks/EXECUTORS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](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, verify integration:

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