DHIVA LABS · LEARN

Appearance

Add providers and API keys ​

A provider is a place that runs models: a cloud service, a local engine, or a logged-in subscription CLI. This page shows how to add each kind to prism.yaml and how to handle API keys safely.

The four provider types ​

typeUse it forNeeds
openaiOpenAI, DeepSeek, Qwen, Mistral, Groq, OpenRouter, Moonshot, and local engines (Ollama, vLLM, LM Studio, llama.cpp server)base_url, and a key for cloud services
anthropicThe Anthropic API (Claude)base_url and a key
claude-codeYour Claude subscription, through the logged-in claude CLIThe CLI installed and logged in
codex-cliYour ChatGPT subscription, through the logged-in codex CLIThe CLI installed and logged in

Keep API keys out of the file ​

Never paste a real API key into prism.yaml. Name an environment variable instead, and Prism reads the key from it when it starts:

yaml
api_key_env: ANTHROPIC_API_KEY

Then set the variable in the terminal that runs prism serve:

bash
export ANTHROPIC_API_KEY=your-key-here
prism serve

You can also write api_key: ${ANTHROPIC_API_KEY}; Prism replaces the ${...} part with the variable's value. Keys never appear in Prism's logs or API responses.

DANGER

Do not commit prism.yaml to a public repository if it contains a literal key. The desktop companion's Providers card writes keys into the file as literal api_key values; it restricts the file so only your user can read it, but the key is still stored in plain text.

Add a cloud provider ​

  1. Add a block under providers:. For Anthropic:

    yaml
    - name: anthropic
  type: anthropic
  base_url: https://api.anthropic.com
  api_key_env: ANTHROPIC_API_KEY
  models:
    - id: claude-sonnet-4-5
      aliases: [claude-sonnet]
      context_window: 200000
      capabilities: [code, reasoning, vision, tools]
      speed: fast
      cost: {input_per_mtok: 3.00, output_per_mtok: 15.00}

  2. For an OpenAI-compatible service, use type: openai and the service's base URL. For DeepSeek:

    yaml
    - name: deepseek
  type: openai
  base_url: https://api.deepseek.com/v1
  api_key_env: DEEPSEEK_API_KEY
  models:
    - id: deepseek-chat
      aliases: [deepseek]
      context_window: 128000
      capabilities: [code, reasoning, tools]
      cost: {input_per_mtok: 0.27, output_per_mtok: 1.10}

  3. Set the environment variables and check the result:

    bash
    prism models

The model id must be the exact name the provider expects. Prices in cost are US dollars per million tokens. Copy them from the provider's price list; Prism uses them only for its cost records and budget. The values above are examples from the project's sample config and may be out of date.

Add a local engine ​

Any local engine with an OpenAI-compatible API works like Ollama in the beginner guide. Use its address as base_url and add local: true:

yaml
- name: lmstudio
  type: openai
  base_url: http://127.0.0.1:1234/v1
  local: true
  models:
    - id: your-model-name
      context_window: 32768
      capabilities: [code]

The address and model name here are placeholders: use the ones your engine shows. local: true matters: offline mode and local:any targets only use local providers.

Use your subscription as a provider ​

If you pay for Claude Pro or Max, or a ChatGPT plan, the logged-in CLI on your machine can answer requests. Prism runs the CLI's headless mode once per request. Nothing is billed per token; usage comes out of your plan.

yaml
- name: claude-subscription
  type: claude-code
  models:
    - id: sonnet                 # sonnet, opus, haiku, or a full model name
      aliases: [claude-sub]
      context_window: 200000
      capabilities: [code, reasoning]

- name: codex-subscription
  type: codex-cli
  models:
    - id: gpt-5.1-codex
      aliases: [codex-sub]
      context_window: 400000
  • Do not set base_url or a key. Prism refuses them for these types.
  • The CLI must be installed and logged in. Check with claude -p hi.
  • If the CLI is not on the PATH the gateway sees, add command: [/home/you/.local/bin/claude] with your real path.
  • Leave cost at zero, since you pay a flat fee.

Limits of subscription providers:

  • Images and tool definitions are refused with a 400 error.
  • Answers come from the CLI, with its own instructions in the context, so they may read like an agent's replies.
  • Each request starts the CLI, which adds a delay.
  • When your plan's limit is reached, the CLI fails and Prism moves to the next model in the failover chain.

Model fields ​

FieldWhat it is for
idThe model name the provider expects. Required
aliasesShort names for routing and requests. Every id and alias must be unique across all providers
context_windowLargest request in tokens. Prism skips a model when the estimated request is bigger
capabilitiesTags such as code, reasoning, vision, tools. Used by targets like local:code
speedA label such as fast or medium, returned by GET /v1/models
costinput_per_mtok and output_per_mtok in US dollars. Zero for local models

Other provider fields: headers adds HTTP headers to every request to that provider, and local marks it as local. All fields are in the reference.

Next steps ​