Skip to content

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.

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 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.

Clients on the Prism machine use 127.0.0.1. For other machines:

  • set [server] host to 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 example https://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 use http://127.0.0.1:18000 on the client machine.

GET /.well-known/prism.json needs no key and returns the per-dialect paths and variable names:

Terminal window
curl -s http://127.0.0.1:18000/.well-known/prism.json | python3 -m json.tool

The 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.

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, /responses and /embeddings are the same routes without the /v1 prefix. A narrowed policy must name every endpoint the client calls.

    A request outside the policy gets 403 with code policy_denied and the dimension that failed, for example the 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, the key query parameter or a /k/prism_it_… base address. A request that also carries a cookie gets 401 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 without max_tokens or a model without a known price can be refused with 403.

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.

Terminal window
export ANTHROPIC_BASE_URL="http://127.0.0.1:18000"
export ANTHROPIC_AUTH_TOKEN="prism"
claude
  • ANTHROPIC_BASE_URL is the origin without /v1; Claude Code appends /v1/messages.
  • Use ANTHROPIC_AUTH_TOKEN: Claude Code sends it as Authorization: Bearer. ANTHROPIC_API_KEY is sent as x-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, set ANTHROPIC_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_TOKEN or in ANTHROPIC_API_KEY. Its anthropic-version and anthropic-beta headers are passed on, not refused.

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"
Terminal window
export PRISM_API_KEY="prism"
codex
  • Codex uses the Responses API (/v1/responses).
  • model must 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 in X-Prism-Responses-Translated: chat_completions and X-Prism-Responses-Dropped (fields it could not carry, such as store).
  • 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_endpoints needs /v1/responses and, for translated requests (auto among 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”
Terminal window
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_KEY
reply = 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.

Terminal window
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.

Terminal window
export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:18000"
export GEMINI_CLI_CUSTOM_HEADERS="Authorization: Bearer prism"
gemini
  • GOOGLE_GEMINI_BASE_URL is the origin; the client appends /v1beta.
  • Gemini CLI sends GEMINI_API_KEY as x-goog-api-key; GEMINI_CLI_CUSTOM_HEADERS sends the key as Authorization: Bearer instead. Prism reads a key from either header on both addresses.
  • Prism serves generateContent and streamGenerateContent only. countTokens, embedContent and model listing answer 404.

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:

Terminal window
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/tags lists Prism’s models. Provider models appear under their own id without the provider:: prefix, because Ollama clients read a:b as model and tag. A :latest tag on a name is ignored.
  • /api/chat and /api/generate are translated to Chat Completions and routed like any other request. Streaming is on by default (NDJSON), as in Ollama.
  • /api/pull succeeds for a model Prism serves and downloads nothing. /api/create, /api/delete, /api/copy and /api/push answer 501.
  • 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.

Terminal window
curl -s http://127.0.0.1:18000/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model": "auto", "messages": [{"role": "user", "content": "Hello"}]}'
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.

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.

  • Response headers: X-Prism-Provider (the provider that served the answer, after any failover), X-Prism-Model, X-Prism-Cost-USD.
  • The model field 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 = true adds a prism object with served_model, provider and the failover trail to non-streaming answers, for harnesses that drop headers.
  • GET /prism/session/last-served with the same X-Prism-Session header returns the last model that served that session.
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