Connect clients
This page tells you how to point an application at Prism: which address to use, which key to give it, and what to set in each client. It covers Claude Code, Codex CLI, the OpenAI and Anthropic SDKs, Gemini CLI, Ollama clients, omp and plain HTTP.
The console shows the same settings, filled in for your installation, under Quick start → Compatible API addresses → Client setup, including a snippet for Ollama clients.
1. Which address
Section titled “1. Which address”Prism serves model requests on two listeners.
| Main address | Managed address | |
|---|---|---|
| Config | [server] host, port |
[server] managed_bind |
| Default | 127.0.0.1:18000, always on |
off |
| Key | any value is served as the owner’s; a person’s prism_it_… key is checked and makes the request theirs |
a prism_it_… key issued in the console is required, in the same places as on the main address |
| Dialects | OpenAI, Anthropic Messages, Gemini, Ollama | OpenAI, Anthropic Messages, Gemini, Ollama (no count_tokens) |
| Plain HTTP | any bind | loopback or a tailnet address (100.64.0.0/10); other addresses need managed_tls_cert and managed_tls_key |
Use the main address for clients on the Prism machine. Anyone who can reach
the main address can send model requests through your accounts, so keep
[server] host on 127.0.0.1 unless the network in front of it is yours.
Use the managed address when clients on other machines need their own keys
that you can revoke. It reads the key from the same places as the main
address (see below) and refuses a request without one, so it is the address
to put behind a public tunnel or proxy.
The main address without a person’s key is for you alone. Requests on it are yours and may use your subscription accounts (Claude, Codex and the other providers you signed in to), and Prism cannot tell who sent them. A subscription serves one person, so give everyone else a user of their own under Users and budgets with a personal Prism key; they connect their own subscriptions, and their requests never use yours.
A person’s key on the main address
Section titled “A person’s key on the main address”A request to the main address that carries a Prism key (prism_it_…) is
served as the managed address serves it: the key is checked, the request is
made for the key’s person, uses only the accounts that person may use, follows
the key’s policy, and its usage and cost are recorded for that person. Put the
key where the client puts an API key: Authorization: Bearer, x-api-key
(Claude Code’s ANTHROPIC_API_KEY, Anthropic SDKs), x-goog-api-key (Gemini
CLI, Google GenAI SDK) or the key query parameter. A revoked or unknown
Prism key is refused with 401; it is never served as the owner’s. Any other
value, such as prism, keeps the request the owner’s. In an organization
(Teams and Enterprise) every model request needs a person’s key, the owner’s included: a
request without one is refused with 401 and code personal_key_required.
The model list (GET /v1/models) stays open without a key.
An organization owner or administrator issues keys on the person’s card
(Users and budgets → Access and activity).
A client with no field for a key (most Ollama apps) takes the key in its base
address: put /k/prism_it_… after the origin, for example
http://prism-host:18000/k/prism_it_… for Ollama and Claude clients or
http://prism-host:18000/k/prism_it_…/v1 for OpenAI clients. Prism removes
the prefix before it serves the request. Anything in the client’s own key
field that is not a Prism key is ignored. The address holds the key, so treat
it as you would the key; revoke the key if the address leaks.
A model request with a Prism key may carry only the query parameters listed
under
Requests with a Prism key;
any other query parameter gets 401, on either address.
A key whose policy carries a spending limit per request ("no_spend_cap"
absent or false) needs the request to cap its output (max_tokens, or
options.num_predict for Ollama); a request without a cap is refused with
403. The console fills in no per-request limit, so this concerns a policy
whose limit was set on purpose.
Address for another machine
Section titled “Address for another machine”Clients on the Prism machine use 127.0.0.1. For other machines:
- set
[server] hostto an address they can reach (for the main address) or[server] managed_bind(for the managed address), and restart Prism; - if clients reach Prism through a name or proxy, set
[server] ingress_public_url(for examplehttps://prism.example.net). Prism shows this origin in the console and in/.well-known/prism.json; it does not change what Prism listens on; - for a loopback-only listener, use an SSH tunnel from the client machine:
ssh -N -L 18000:127.0.0.1:18000 user@prism-host, then usehttp://127.0.0.1:18000on the client machine.
Ask Prism for its connection settings
Section titled “Ask Prism for its connection settings”GET /.well-known/prism.json needs no key and returns the per-dialect paths
and variable names:
curl -s http://127.0.0.1:18000/.well-known/prism.json | python3 -m json.toolThe connection object lists, for each dialect, base_path (what to append
to the origin for the client’s base URL), protocol_root (where the client
sends requests), base_url_env and api_key_env. The ollama dialect has an
empty api_key_env (Ollama clients send no key) and carries
key_in_path: true: where a key is required, it goes into the address as
/k/<key> right after the origin. credential is none in a personal installation: the
listeners that serve this document take any key. In an organization it is
personal_key, and the notes say that every model request needs a person’s
Prism key. managed_ingress is true when a
managed address is configured. When [server] ingress_public_url is set it
appears as public_url, and public_url_credential is integration_bearer
if a managed address is configured, otherwise none.
2. Keys
Section titled “2. Keys”Main address. Any value works as the owner’s key, for example prism;
most clients refuse to start without one. Your own Prism key makes the
requests and their cost yours, and in an organization it is required. Get it
in one click: Overview → Connect your apps → My Prism key → Issue my key.
The key is shown once, together with addresses that carry it for apps with
no key field; Replace my key issues a new one and stops your other Prism
keys. Your agent keys are listed too, marked “agent key”; a replace leaves
them working. The key has no spend limit per request (budgets limit spend)
and does not expire.
A key whose permissions are narrower (for example one issued under v0.40.0,
which allowed no tools) shows Give full access: one click changes what
the key may do and keeps the same key, so no app needs a new one.
In an organization, when an owner or administrator has narrowed one of your
keys, that narrower policy applies to all of your keys: a new key gets it,
and a key cannot be given more than it.
Managed address. Issue a key in the console: Configuration → API keys → Add API key (owner only). There is no CLI command for it.
-
The key (
prism_it_…) is shown once. Store it in the client’s key variable. -
A key expires after 90 days unless you set another expiry.
-
The key’s policy lists the endpoints it may call in
allowed_endpoints. The console starts the policy with"*", every endpoint, so nothing has to be added for Rerank (/v1/rerank) or TypeSafe (/v1/systemone). A policy narrowed to a list still names the dispatch, not the literal path: Anthropic Messages and Gemini requests are checked as/v1/chat/completions, and/models,/chat/completions,/responsesand/embeddingsare the same routes without the/v1prefix. A narrowed policy must name every endpoint the client calls.A request outside the policy gets
403with codepolicy_deniedand the dimension that failed, for examplethe integration key policy does not allow this request: endpoint "/v1/rerank". -
Put the key where the client puts an API key, as on the main address:
Authorization: Bearer,x-api-key,x-goog-api-key, thekeyquery parameter or a/k/prism_it_…base address. A request that also carries a cookie gets401 unauthorized. -
Revoke a key on the same page.
-
A key a person issues for themselves in the console has no spend limit per request (
"no_spend_cap": true), every endpoint and every tool ("*"), the longest answer time (24 hours) and up to 1024 concurrent requests. Their spend is limited by the budgets set for them and their team. A request may still set its own spend limit. A key with a spend limit per request is priced in advance from the request size and the model’s longest answer, so a large request, a request withoutmax_tokensor a model without a known price can be refused with403.
3. Clients
Section titled “3. Clients”The examples use the main address on the Prism machine. For the managed
address, replace the origin and use the issued key instead of prism.
Claude Code
Section titled “Claude Code”export ANTHROPIC_BASE_URL="http://127.0.0.1:18000"export ANTHROPIC_AUTH_TOKEN="prism"claudeANTHROPIC_BASE_URLis the origin without/v1; Claude Code appends/v1/messages.- Use
ANTHROPIC_AUTH_TOKEN: Claude Code sends it asAuthorization: Bearer.ANTHROPIC_API_KEYis sent asx-api-key; Prism reads a key from either header on both addresses. - Claude Code’s model names (for example
claude-sonnet-4-5) are routed to a provider that serves that model. To let Prism choose, setANTHROPIC_MODEL=auto. - WebSearch and other Anthropic server tools work only when an Anthropic provider is connected; Prism sends those requests to it unchanged.
- Managed address: Claude Code works there with the issued key in
ANTHROPIC_AUTH_TOKENor inANTHROPIC_API_KEY. Itsanthropic-versionandanthropic-betaheaders are passed on, not refused.
Codex CLI
Section titled “Codex CLI”Codex reads its provider from ~/.codex/config.toml, not from
OPENAI_BASE_URL:
model_provider = "prism"model = "openai::gpt-5-mini"
[model_providers.prism]name = "Prism"base_url = "http://127.0.0.1:18000/v1"env_key = "PRISM_API_KEY"wire_api = "responses"export PRISM_API_KEY="prism"codex- Codex uses the Responses API (
/v1/responses). modelmust be a model that Prism lists in/v1/models; replace the example value with one of those ids. With a concrete model and no provider that offers the Responses API for it, Prism translates the request to Chat Completions and reports it inX-Prism-Responses-Translated: chat_completionsandX-Prism-Responses-Dropped(fields it could not carry, such asstore).model = "auto"lets Prism choose from all connected models, including Claude through a subscription, as for chat clients; the request is translated to Chat Completions as above. A request that cannot be translated (previous_response_id, hosted tools other than web search) is chosen only among models with the Responses API.- Managed address: with a narrowed key policy,
allowed_endpointsneeds/v1/responsesand, for translated requests (autoamong them),/v1/chat/completions. The console starts the policy with"*", which allows both (section 2).
OpenAI SDK (Python, JavaScript) and OpenAI-compatible tools
Section titled “OpenAI SDK (Python, JavaScript) and OpenAI-compatible tools”export OPENAI_BASE_URL="http://127.0.0.1:18000/v1"export OPENAI_API_KEY="prism"from openai import OpenAI
client = OpenAI() # reads OPENAI_BASE_URL and OPENAI_API_KEYreply = client.chat.completions.create( model="auto", messages=[{"role": "user", "content": "Hello"}],)print(reply.choices[0].message.content)The base URL ends in /v1. Prism also serves /chat/completions,
/responses, /embeddings and /models without the /v1 prefix, for
tools that drop it.
Anthropic SDK (Python, TypeScript)
Section titled “Anthropic SDK (Python, TypeScript)”export ANTHROPIC_BASE_URL="http://127.0.0.1:18000"export ANTHROPIC_API_KEY="prism"import anthropic
client = anthropic.Anthropic()reply = client.messages.create( model="auto", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}],)print(reply.content[0].text)ANTHROPIC_API_KEY works on both addresses. SDK releases for API version
2026-10-21 (Python 2.0.0, TypeScript 1.0.0, Go 2.0.0 and the others) send it
as Authorization: Bearer, earlier releases as x-api-key; Prism reads a key
from either header. The
anthropic-version header the SDK always adds is passed on: a version later
than 2023-06-01 only to the Claude API (api.anthropic.com), and
2023-06-01 to every other Anthropic-compatible provider. Version
2026-10-21 refuses temperature, top_p and top_k; Prism never adds them
to a request that carries it, and a request in the Chat Completions format is
sent to Anthropic with 2023-06-01.
Gemini CLI and the Google GenAI SDK
Section titled “Gemini CLI and the Google GenAI SDK”export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:18000"export GEMINI_CLI_CUSTOM_HEADERS="Authorization: Bearer prism"geminiGOOGLE_GEMINI_BASE_URLis the origin; the client appends/v1beta.- Gemini CLI sends
GEMINI_API_KEYasx-goog-api-key;GEMINI_CLI_CUSTOM_HEADERSsends the key asAuthorization: Bearerinstead. Prism reads a key from either header on both addresses. - Prism serves
generateContentandstreamGenerateContentonly.countTokens,embedContentand model listing answer404.
Ollama clients
Section titled “Ollama clients”Prism answers the Ollama API on the main address, so tools that speak only Ollama, or offer an “Ollama” provider option, reach every model Prism routes.
Ollama CLI and the ollama Python and JavaScript libraries:
export OLLAMA_HOST="http://127.0.0.1:18000"import ollama
print([m.model for m in ollama.list().models])reply = ollama.chat(model="auto", messages=[{"role": "user", "content": "Hello"}])print(reply.message.content)Open WebUI: set OLLAMA_BASE_URL=http://127.0.0.1:18000. Other tools (Zed,
Continue, Cline, n8n, Enchanted, Home Assistant): choose the Ollama provider
and enter http://127.0.0.1:18000 as its address.
/api/tagslists Prism’s models. Provider models appear under their own id without theprovider::prefix, because Ollama clients reada:bas model and tag. A:latesttag on a name is ignored./api/chatand/api/generateare translated to Chat Completions and routed like any other request. Streaming is on by default (NDJSON), as in Ollama./api/pullsucceeds for a model Prism serves and downloads nothing./api/create,/api/delete,/api/copyand/api/pushanswer501.- The Ollama API is not served on the managed address.
omp (oh-my-pi) can sign in to Prism instead of having a key in its settings:
it installs an extension from Prism with one line, then /login in omp
shows a link and a code that you allow in the Prism console. Models then
appear as prism-signin/<model>. The console shows the line with your
address under Quick start → Client setup; the steps are in
Sign in from an app.
curl -s http://127.0.0.1:18000/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"model": "auto", "messages": [{"role": "user", "content": "Hello"}]}'4. Model names
Section titled “4. Model names”model value |
What Prism does |
|---|---|
auto (or empty) |
Chooses a model with the default strategy (balanced unless changed) |
cheap, fast |
Chooses with that strategy |
smart |
Chooses with the quality strategy |
local |
Uses local models only; never sends the request to a cloud provider |
triage, reasoning, reasoning-max, cheap-toolcall |
Built-in roles |
prism/auto, prism/strong, prism/frontier, prism/reasoning, prism/reasoning-max, prism/private |
Policy models listed in /v1/models |
A name from [routing.role_aliases] |
Your role alias |
provider::model, for example openrouter::anthropic/claude-sonnet-4.5 |
That model at that provider only (another account of the same provider may serve it). Other providers are tried only with X-Prism-Allow-Provider-Failover: true or [routing] allow_provider_failover = true |
A model id, for example gpt-5-mini |
That model at any provider that serves it |
balanced, quality and private are strategy names, not model names.
Send them in the X-Prism-Strategy header with "model": "auto".
"model": "balanced" is treated as a model id and fails with
400 no provider has exact model_id balanced.
/v1/models lists provider models as provider::model, plus role aliases and
prism/* policy models. It does not list auto, cheap, fast, smart and
local; they are listed in /.well-known/prism.json under
model_selection.
5. Name your agent
Section titled “5. Name your agent”Send X-Prism-App: <name> with a stable name per agent. Prism uses it in
reports (console → Agents) and, when you map the name to a routing profile,
to choose that profile. Without the header Prism names the agent from its
User-Agent and request shape.
Clients that cannot add headers still work; they appear under the name Prism infers.
6. Which model answered
Section titled “6. Which model answered”- Response headers:
X-Prism-Provider(the provider that served the answer, after any failover),X-Prism-Model,X-Prism-Cost-USD. - The
modelfield of a Chat Completions or Anthropic Messages answer carries the model that served it (for"model": "auto"it is the chosen model). Ollama answers repeat the requested name. [harness] announce_served_model = trueadds aprismobject withserved_model,providerand the failover trail to non-streaming answers, for harnesses that drop headers.GET /prism/session/last-servedwith the sameX-Prism-Sessionheader returns the last model that served that session.
7. Troubleshooting
Section titled “7. Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
401 unauthorized on the managed address |
No key; a key that is revoked, expired or unknown; two different keys in one request; a cookie; or a query parameter Prism does not accept next to a key | Put one prism_it_… key where the app takes an API key; issue a new key; see Requests with a Prism key for the accepted query parameters |
401 personal_key_required on the main address |
The installation is an organization and the request has no Prism key | Get your key under Overview → My Prism key (or from an administrator) and put it where the app takes an API key |
401 unauthorized on the main address |
A prism_it_… key that is revoked, expired or unknown, two different keys in one request, a /k/ address without a Prism key, or a query parameter Prism does not accept next to a key |
Issue a new key; send one key; see Requests with a Prism key for the accepted query parameters |
403 with code policy_denied on the managed address |
The endpoint is not in the key’s allowed_endpoints |
Add the endpoint to the policy (section 2); the reply names the endpoint that was refused |
403 forbidden on the managed address |
The client sent OpenAI-Organization, OpenAI-Project or a X-Prism-Idempotency* header |
Remove those headers; provider account selection stays on the Prism side |
404 route_not_found |
Path not served (for example /api/tags on the managed address, /v1/responses/{id}) |
Check the client’s base URL: /v1 for OpenAI clients, origin only for Claude and Gemini clients |
400 no provider has exact model_id … |
The model name is not served by any connected provider | Pick an id from /v1/models, or use auto |
503 providers_unavailable |
No connected provider can serve the request (none connected, all unhealthy, or no Responses-API provider for /v1/responses with auto) |
Connect a provider in the console (AI providers); check Diagnostics |
402 billing_required |
The provider account has no funds | Top up the account, then clear the mark (console → AI providers) |
429 budget_exceeded |
A [[budget.limits]] threshold with action = "reject" was reached, or the model named in the request (or every account serving it) has spent its [[budget.model_limits]] / [[budget.account_limits]] budget |
Wait for the period to reset (Retry-After), raise the limit, or send auto |
Browser app gets 403 from the main address |
The main address refuses cross-origin browser requests without a key | Put a Prism key (prism_it_…) in the app’s API key field, or add the app’s origin to [server] cors_allowed_origins |