Configuration reference
Every command, option and config key in the DL Prism 0.2.0 gateway.
Commands
| Command | What it does |
|---|---|
prism serve [-c config] [--listen addr] [--offline] | Starts the gateway |
prism models [-c config] | Lists every configured model |
prism explain [-c config] [-m model] <prompt> | Shows the routing decision for a prompt, without calling a model |
prism usage [-c config] | Shows this month's spend, budget and per-model totals |
prism mcp [--gateway url] [--api-key key] | Runs the MCP server over stdio, for Claude Code and Codex |
prism version | Prints the version |
prism help | Prints the list of commands |
Options
| Option | Commands | What it does | Default |
|---|---|---|---|
-c <file> | serve, models, explain, usage | Config file to use | See search order below |
--listen <addr> | serve | Overrides server.listen | from the config |
--offline | serve | Routes to local providers only | off |
-m <model> | explain | Model to resolve instead of automatic routing | auto |
--gateway <url> | mcp | Gateway address. A bare host:port is accepted | $PRISM_GATEWAY, else http://127.0.0.1:8130 |
--api-key <key> | mcp | Key sent to the gateway | $PRISM_API_KEY |
Config search order: the -c file, then ./prism.yaml, then ~/.config/prism/prism.yaml.
prism.yaml keys
Unknown keys are an error, so a typo stops the gateway with a message instead of being ignored.
Top level
| Key | What it does | Default |
|---|---|---|
server | Listen address and client keys | |
providers | List of providers. At least one is required | |
routing | Default model, rules and fallbacks | |
budget | Monthly budget | |
offline | true routes to local providers only, like --offline | false |
server
| Key | What it does | Default |
|---|---|---|
listen | Address and port to listen on | 127.0.0.1:8130 |
api_keys | List of keys clients must send. Required when listen is not a loopback address | [] (any key accepted) |
providers[]
| Key | What it does |
|---|---|
name | Unique name. Required |
type | openai, anthropic, claude-code or codex-cli. Required |
base_url | Address of the API, starting with http:// or https://. Required for openai and anthropic; refused for the CLI types |
api_key_env | Name of an environment variable holding the key |
api_key | The key itself. ${VAR} references are expanded. Prefer api_key_env |
headers | Extra HTTP headers sent with every request |
local | true marks a provider on your machine |
command | Program and arguments for the CLI types, when not on PATH. Defaults to claude or codex; refused for the HTTP types |
models | List of models. At least one is required |
providers[].models[]
| Key | What it does |
|---|---|
id | Model name at the provider. Required |
aliases | Extra names. Ids and aliases must be unique across all providers |
context_window | Largest request in tokens. Larger requests skip this model |
capabilities | Tags such as code, reasoning, vision, tools |
speed | A label such as fast or medium |
cost.input_per_mtok | US dollars per million input tokens. Default 0 |
cost.output_per_mtok | US dollars per million output tokens. Default 0 |
routing
| Key | What it does |
|---|---|
default | Model used in automatic mode when no rule matches |
rules | List of {if: {...}, then: model}, checked top to bottom; first match wins |
fallbacks | Map of model to an ordered list of backup models |
Rule conditions (if): task (code, security, docs, vision, general), language, vision, offline, budget_exceeded, min_context_tokens. Targets (then): a model id or alias, local:any or local:<capability>. Every model named in default, rules and fallbacks must exist, or the gateway does not start.
budget
| Key | What it does | Default |
|---|---|---|
monthly_usd | Spend per calendar month after which budget_exceeded matches. 0 means no budget | 0 |
HTTP endpoints
| Method and path | What it does |
|---|---|
POST /v1/chat/completions | OpenAI-compatible chat, streaming and non-streaming |
POST /v1/messages | Anthropic Messages-compatible chat, streaming and non-streaming. Tool definitions are refused |
POST /v1/messages/count_tokens | Token estimate for Anthropic SDKs |
GET /v1/models | auto plus every model, with Prism details |
POST /v1/route/explain | The routing decision for a request body, without calling a model |
GET /admin/usage | This month's spend, budget, per-model totals and 30 days of daily cost |
GET /admin/status | Version, uptime, offline mode, listen address and provider health |
GET /admin/routing | The loaded default, rules and fallbacks |
GET /healthz | Health check |
GET / | The web dashboard |
When server.api_keys is set, send a key as Authorization: Bearer <key> or x-api-key: <key>.
Errors: an unknown model is 404, a routing problem is 400, and a request where every candidate failed is 502.
Response headers
| Header | Value |
|---|---|
X-Prism-Mode | auto or manual |
X-Prism-Provider | Provider that answered |
X-Prism-Model | Model that answered |
X-Prism-Reason | Why, plus failed over after: when a failover happened |
Environment variables
| Variable | Used by | What it does |
|---|---|---|
The names in api_key_env | serve | Provider API keys |
XDG_DATA_HOME | all | Base folder for usage and projects. Default ~/.local/share |
PRISM_GATEWAY | mcp | Gateway address |
PRISM_API_KEY | mcp | Key sent to the gateway |
Files
| Path | What it is |
|---|---|
./prism.yaml or ~/.config/prism/prism.yaml | The config file |
~/.local/share/prism/usage.jsonl | Usage records: time, provider, model, tokens, cost |
~/.local/share/prism/workbench/ | Projects, chats, attached files and agent workspaces |
~/.var/app/com.dhivalabs.prism.desktop/data/prism/ | Usage records when you use the Flatpak |
Defaults at a glance
| Setting | Default |
|---|---|
| Listen address | 127.0.0.1:8130 |
| Circuit breaker | 3 failures in a row, then 30 seconds demoted |
| Daily usage window | 30 days |