---
title: Custom Providers (bring your own web AI provider)
---

# Custom Providers (bring your own web AI provider)

## What it is

**Custom Providers** lets you add almost any web AI provider yourself and run it as a
named provider inside the Claude Code harness — without waiting for Omniscio to build a
first-class integration for it. You give it a name, a base URL, an API key, and the model
ids it serves, and it shows up alongside the built-in providers when you pick a model for a
session.

It supports two wire formats:

- **OpenAI-compatible** endpoints (`/v1/chat/completions`-style APIs — the format most
  hosted inference services expose: Groq, Together, Fireworks, a local server, etc.).
- **Anthropic-compatible** endpoints (the Messages API shape).

**OpenRouter ships built-in** as a ready-made custom provider, so you can reach hundreds of
models with a single OpenRouter key without configuring anything by hand.

## Where to find it

Both halves of the feature live in **Settings → Accounts & AI**: the **Providers** area is where a custom provider is added and managed, and the **Custom Providers** card there carries the switch that turns custom providers on or off. Once an endpoint is saved it joins the model picker on the session composer's Harness · Provider · Model bar, so the place you actually choose it is the same place you choose any other provider when starting a session.

## How it behaves

### How to use it

1. Open **Settings → Accounts & AI** and find the **Providers** area.
2. Add a **Custom Provider**: pick the format (OpenAI-compatible or Anthropic-compatible),
   then fill in a display **name**, the **base URL**, your **API key**, and the **model
   ids** the provider offers.
3. Save. The provider (and its models) now appear in the model picker on the session
   composer's Harness · Provider · Model bar, so you can spawn sessions against it like any
   other provider.

Your API key is checked when you save (the same "Checking… / Save anyway" flow the other
provider key fields use), so a typo is caught before you rely on it. If the provider says
no but you know the key is good, **Save anyway** stores it regardless — the check is one
answer from a remote service, and it is not always right.

### Settings

Setting key: `customProvidersEnabled`, on by default, with its **Allow custom provider
sessions** switch at the top of the Custom Providers card in Settings → Accounts. Turning it
off hides your custom providers (and the built-in OpenRouter entry) from the session picker
and refuses a launch against one; your saved endpoints, model lists and keys are retained for
when you turn it back on.

> **It used to default OFF, and that was a bug — fixed 2026-09-12.** This one setting does two
> jobs: it reveals the feature AND it is the spawn gate for the two carriers. The feature was
> marked shipped, which makes the Settings card visible for everyone *without* reading the
> setting — so the card appeared, you could add a provider, and then every launch was refused
> with a "Set up" prompt that led nowhere, because a shipped feature gets no Labs toggle and the
> hidden carriers get no provider card of their own. The built-in **OpenRouter** entry was
> caught by the same gap. The default is now ON, existing installs are migrated once, and the
> switch above is its real home.

Note that **Show alternative AI providers** (Settings → Accounts) is a separate, earlier gate
that ships off: with the master switch off, no non-Claude provider appears in the picker,
custom ones included.

### How it works

- A custom provider is stored as one of two **carriers** internally — `customOpenai` or
  `customAnthropic` — which route the request through the matching OpenAI- or
  Anthropic-shaped client.
- The **base URL is validated** before it is accepted: only `http:` / `https:` URLs are
  allowed, and URLs pointing at loopback / link-local / private-network addresses (for
  example `127.0.0.1`, `169.254.169.254`, `10.x.x.x`) are rejected. This is a
  server-side-request-forgery (SSRF) guard — a custom provider is a remote web API, not a
  path to a machine on your own network.
- The **API key lives in the main process only** and is stored encrypted; it is never sent
  to the renderer, mirroring how every other provider credential is handled.
- **OpenRouter** is provided as a built-in custom-provider entry so it needs no manual base
  URL — just the key.
- **The OpenRouter entry's model list keeps itself current.** OpenRouter carries 430 models
  and adds several a week, so rather than shipping a list that goes stale, Omniscio picks the
  defaults from OpenRouter's own catalog each day: models that can call tools, from a
  first-party frontier lab, current-generation — about a dozen, newest first. Every other
  built-in field stays fixed.
- **You can pin your own list instead** — the **models** button on the OpenRouter row (built-in
  entries have no full edit form, only this). One model id per line, and any OpenRouter model
  works, not just the ones shown. Saving stops the automatic refresh so your choice is never
  overwritten; **Use automatic again**, or clearing the box, hands it back. The list can never
  be saved empty — an empty picker would leave you unable to start a session — so Omniscio
  falls back to the list it ships with.

## Related

Where custom providers sit in the wider picture — the cheap and utility AI calls Omniscio makes, and the shared model picker they appear in — is on the [AI providers](ai-providers.md) page, and where the keys themselves are stored and checked on save is on the [API keys](api-keys.md) page. The built-in OpenRouter entry this page describes has its own page at [OpenRouter provider](openrouter-provider.md), and changing the provider of a session that is already running is covered by [Switching providers](switching-providers.md).

- [ai-providers.md](ai-providers.md) — how Omniscio routes its cheap/utility LLM calls and the shared model picker
- [api-keys.md](api-keys.md) — where provider keys live and how the save-time key check works