Omniscio

Custom Providers (bring your own web AI provider)

Custom Providers lets you add almost any web AI provider yourself — a display name, a base URL, an API key and the model ids it serves — and run it as a named provider inside the session model picker, in either OpenAI-compatible or Anthropic-compatible wire format. Covers adding one, the URL rules (https for any host, private https addresses allowed, plain http for localhost or, behind a Safety switch, a computer on your home network), an optional custom certificate, and the built-in OpenRouter entry.

On this page

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 not checked when you save: the key dialog stores whatever you paste, and nothing is sent to the provider until a session actually uses it. A mistyped key shows up as the provider refusing that session's first request, not as a warning in Settings.

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, and the rule depends on the scheme:
    • https:// is accepted for any host, including a private address such as https://192.168.1.20:8443 or a name on your own network. That was always allowed; the older wording of this page, which said private addresses were rejected, was wrong.
    • http:// to localhost (localhost, 127.0.0.1, ::1) is always accepted: a local proxy on this computer.
    • http:// to any other host is accepted only when Settings → Safety → Allow private network addresses is on and the host is provably on your home network: a literal private, unique-local or carrier-grade-NAT address (10.x.x.x, 172.16–31.x.x, 192.168.x.x, 100.64–127.x.x, fc00::/7), or a name that can only mean a home network (a single word such as nas, or a name ending .local, .lan, .home.arpa or .internal) whose every resolved address is one of those. A cloud-metadata address (169.254.169.254 and its relatives), a link-local address, a public address, or a public name over http is always refused, and the message says to use https instead.
    • The check runs again every time a session starts, and every time the local model proxy starts. A name that resolved to your home network when you saved it but resolves elsewhere now is refused with a notice in the session, and for an OpenAI-compatible provider it is left out of the proxy configuration.
    • Tailscale addresses count as your home network. Addresses from 100.64.0.0/10 are what Tailscale gives each device on your tailnet, and Tailscale encrypts the traffic between your devices with WireGuard, so plain http to one of them is not sent in the clear. That is why this range is allowed alongside the ordinary private ranges.
    • The dialog warns while the URL is plain http: your key is sent without encryption on your home network. It also says that turning on the Safety switch lets your agents reach private addresses as well, not only this provider.
  • An optional custom certificate (Advanced in the add/edit form) lets a provider whose server uses a certificate from your own authority work. Paste one or more CERTIFICATE blocks (up to 64 KiB); anything else in the text, a private key above all, is refused. After saving, the form shows who each certificate names, its SHA-256 fingerprint and its validity dates. The certificate is written to a private file for that one session and handed to the session's programs, so every program the session runs (MCP servers, hooks, package installs) trusts it; it is never added to Omniscio itself or to another session. It is used by Anthropic-compatible providers only: the OpenAI-compatible type goes through the local model proxy, which does not use it. A session on an SSH or cloud computer is refused for a provider that carries a certificate, because the file cannot be sent there.
  • 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.

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 page, and where the keys themselves are stored and checked on save is on the API keys page. The built-in OpenRouter entry this page describes has its own page at OpenRouter provider, and changing the provider of a session that is already running is covered by Switching providers.

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

Last verified 2026-10-30