Configure Magpie
Magpie has one idea behind its config: add a provider once, and its models show up in every agent's picker as provider/model. This page covers adding providers, which file Magpie writes to, which file each agent reads, and the two things that surprise most people on day one.
The whole config, in five commands
magpie presets # the vendors magpie knows: vendors, relays, local
magpie provider add deepseek sk-… # a preset needs only the key
magpie provider test deepseek # one tiny request per API, with latency
magpie claude deepseek/deepseek-chat # point Claude Code at it
magpie providers # host, key, exposed models, who uses whatNo magpie init, no config file to hand-edit. Local servers such as Ollama need no key at all: magpie provider add ollama.
Add a provider
Presets are grouped into vendors, relays and local servers, so magpie presets is the place to start if you are not sure of a vendor's id. A preset knows the base URLs, the API shapes and the documented models — you supply the key.
magpie presets # what magpie knows, grouped
magpie provider add deepseek sk-… # a vendor
magpie provider add openrouter sk-or-… # a relay
magpie provider add ollama # local — no key
magpie provider add lmstudio # local — no key
magpie providers # every provider: host, key, models, users
magpie provider deepseek # one provider in detail
magpie provider models deepseek # re-fetch the vendor's model list
magpie provider test deepseek # one tiny request per API, with latency
magpie provider key deepseek sk-… # replace the key
magpie provider rm deepseek # remove itmagpie provider test is worth running after every new provider: it fires one small request per API the vendor supports and reports the latency, so a provider that only speaks OpenAI-style shows up as exactly that before you point an agent at it.
Custom and relay providers
Anything the presets do not know takes the same shape — a name, a base URL and a key. A custom provider accepts url= for an OpenAI-compatible base, anthropic= for an Anthropic-compatible base, or both:
magpie provider add "My Relay" url=https://relay.example.com/v1 key=sk-… models=gpt-5.5,claude-sonnet-5
# a vendor with both API shapes, plus a separate Responses endpoint
magpie provider add "My Relay" \
url=https://relay.example.com/v1 \
anthropic=https://relay.example.com \
responses=https://relay.example.com/v1/responses \
key=sk-… models=gpt-5.5,claude-sonnet-5url=— an OpenAI-compatible base URLanthropic=— an Anthropic-compatible base URLresponses=— when the vendor serves a separate Responses endpointcatalog=— borrow a model list from models.dev instead of the vendor'smodels=— name exactly which models to expose to your agents
Every one of those also works as an override on a preset, so a vendor that moves its endpoint or charges for a plan the preset does not know can be corrected without dropping back to a fully custom provider.
Where Magpie keeps its config
Magpie's own state is one file:
~/.config/magpie/providers.jsonProviders, their keys, which models each one exposes, and routing groups — including a group's classifier model and each rule's use and intent — all live there. Your agents never hold vendor keys or vendor URLs; they hold a provider/model name and the gateway address.
The gateway listens on http://127.0.0.1:3425/v1 and speaks OpenAI chat completions, OpenAI Responses and the Anthropic Messages API, translating between them on the way out. That is why Claude Code can run a model whose vendor only serves an OpenAI-style API.
The config file for every agent
Magpie touches only the keys it needs to in each agent's own file — comments, ordering and indentation survive, and writes are atomic. Here is the file behind each agent, so you always know what to look at (or back up) when a switch does not take.
| Agent | Config file | Fields Magpie sets |
|---|---|---|
| Claude Code | ~/.claude/settings.json | provider, model, opus/sonnet/haiku/fable |
| Claude Desktop | ~/Library/Application Support/Claude-3p/configLibrary/ | provider (third-party gateway mode) |
| Codex | ~/.codex/config.toml | provider, model, effort |
| Gemini CLI | ~/.gemini/settings.json, ~/.gemini/.env | auth, model |
| OpenCode | ~/.config/opencode/opencode.json(c) | model, small |
| MiMo Code | ~/.config/mimocode/mimocode.json(c) | model, small |
| Pi | ~/.pi/agent/settings.json | model |
| OmO (omo-ai) | ~/.omo/agent/settings.json | model |
| Goose | ~/.config/goose/config.yaml | model |
| Cursor CLI | ~/.cursor/cli-config.json | model |
| Copilot CLI | ~/.copilot/settings.json | model |
| Crush | ~/.config/crush/crush.json | large, small |
| Kimi Code | ~/.kimi/config.toml | model (a magpie provider) |
| Qoder (CLI) | ~/.qoder/settings.json | model, effort |
| Grok Build | ~/.grok/config.toml | model, effort |
| Devin | ~/.config/devin/config.json | model |
| Cline (CLI) | ~/.cline/data/settings/providers.json | model, effort |
| Droid (Factory) | ~/.factory/settings.json | model (as BYOK customModels) |
| ZCode | ~/.zcode/v2/config.json | provider |
| WorkBuddy | ~/.workbuddy/models.json | provider |
Several agents let you move their config directory with an environment variable — $OPENCODE_CONFIG_DIR, $KIMI_SHARE_DIR, $GROK_HOME, $CLINE_DIR, $QODER_CONFIG_DIR, $DSH_HOME, $HANA_HOME and others. Magpie respects those. Only agents that are installed or configured on the machine appear in the app at all.
Which models appear in the picker
Nothing is compiled in. With a key in hand, Magpie asks the vendor which models it serves and offers exactly those; for vendors that serve no list, the models.dev catalog supplies names and reasoning efforts, and refreshes itself in the background once it goes stale. A model released this morning is in the picker on the next refresh.
magpie models # the catalog your agents see
magpie provider models deepseek # re-fetch this vendor's list
magpie claude moonshot/kimi-k3 # point Claude Code at one of themEach agent can also have its own shortened list: under an agent's name on the Agents page, “Showing 5 / 32 models” opens its picker contents — click a model to take it out of that agent's list, or put it back. Other agents keep using it, and new models still show up. Codex's own /model menu is included in that.
provider/model. OpenCode, MiMo Code, Pi, OmO, Goose, Crush, omp and Hermes Agent expect the full provider/model form; single-model agents just take the model.
Plugins and subscriptions
If you already pay for Claude Code, Codex (ChatGPT) or Copilot, signing in there makes that login a provider in Magpie — every other agent can use its models through the gateway, with nothing copied and no key to paste. For a plan Magpie cannot sign in to itself, an OpenCode provider plugin can: the npm packages OpenCode users install to sign in to a plan work in Magpie the same way, run on Bun, which Magpie downloads the first time a plugin needs it.
magpie plugin add opencode-gemini-auth # an npm package, or a path to your own
magpie plugin # the plugins, what each signs in to, and whether you are
magpie plugin login google-plugin # its sign-in: method, questions, browser or a key
magpie plugin logout google-plugin
magpie plugin off opencode-gemini-auth # on brings it back
magpie plugin rm opencode-gemini-auth
magpie plugin update # update them allA provider id Magpie already carries — google, openai, anthropic — becomes <id>-plugin when a plugin signs in to it. In the app it is Settings → Plugins, and the providers a plugin signs in to appear under Add provider → From plugins.
Telling Magpie what a model costs
Every call is counted at its effective price: the price you set for that provider and model, else the provider's own catalog, else what models.dev lists for the model's maker. That last one is the default and it is wrong for any provider charging off-list — a discounted relay or a multiplier gets counted at the maker's list price.
magpie model price relay-a/gpt-5.5 # what it counts at, and where that came from
magpie model price relay-a/gpt-5.5 0.12,0.60,0.01,0.15 # input,output,cache read,cache write
magpie model price relay-a/gpt-5.5 --reset # take your price off this model
magpie model prices # every model you pricedThe four numbers are USD per million tokens, and all four are required — a price missing one would understate the rest of every call. 0 means served at no cost, which is a price rather than the absence of one. Lookup order is: this model's price → a <provider id>/* price covering that provider → the provider's own catalog → models.dev for the maker. --reset removes the first and tells you when a <provider id>/* price is still in force; reset that one by name to clear it too.
A price is one provider's tariff for one model, not a property of the model: the same model served by two providers keeps two separate prices. This only changes what the usage ledger and session totals report — nothing an agent can see moves.
Two things that surprise people
ANTHROPIC_API_KEY or OPENAI_API_KEY exported in your shell, or sitting in a dotfile, has no effect on Magpie. The key has to be added in Magpie itself — magpie provider add <vendor> <key>, or Add provider in the app. If a provider shows as unauthenticated right after you exported a key, this is why.
Other things worth knowing
- A switch is a config edit, not a restart. Magpie rewrites the agent's next request through the gateway; you do not need to relaunch the agent.
- Profiles snapshot everything at once. In the TUI,
ssaves a profile andpopens the list; switching a profile puts every agent back the way the profile had it, in one move. - Failover is per provider. If a key is rate-limited or out of credit, Magpie can move to another of that provider's keys or models rather than failing the request.