Self-host the Magpie AI gateway: switch models freely in Claude Code, Codex and other agents

Claude Code calls Anthropic's models by default, and Codex calls OpenAI's. To try DeepSeek in Claude Code, or to move to another provider when one runs out of quota, you have to change addresses and keys in each tool's config files.

Magpie is an open-source (MIT) AI gateway built for this. You connect your providers to Magpie, and your agents only need Magpie's address. It speaks the OpenAI Chat, OpenAI Responses, Anthropic Messages and Gemini formats and translates between them, so Claude Code can use models that aren't Anthropic's. It also offers:

• Failover and routing groups: when a model errors or runs out of quota, Magpie moves to a backup model or another account, and the agent never sees the error.
• Usage and cost: tokens, cache hit rate and estimated cost, by model and by client.
• Gateway keys: a key of its own for each client, with its own limits and models.

Magpie usually runs on your own computer. This post uses Zenavo's Magpie template to run it on a server instead, so your laptop, your desktop and your teammates' computers share one setup. If what you need is API keys and quotas for a whole team, see also New API: New API is about managing a team's API keys in one place, Magpie about letting each agent pick any model.

The server, Zenavo and the model APIs are billed separately. Magpie forwards and counts requests; it doesn't make model calls cheaper.

Deploy Magpie

First connect a Linux server to Zenavo, then open the Magpie template, choose the server and deploy.

The template currently sets:

Setting	Value or purpose
Image	ghcr.io/yetone/magpie:latest
Command	web --addr 0.0.0.0:3430 --no-open, which runs the browser UI
HTTP port	3430, for both the browser UI and the API your agents call
Volume	/config, which holds providers, gateway keys, sign-ins and usage
MAGPIE_WEB_KEY	Generated when the project is created; the key that signs you in to the browser UI
Memory	512 MB recommended

latest follows upstream. Before you rely on it, go to the service's Settings → Source and change the tag to a version you have tested, or to stable, Magpie's weekly channel.

Add a domain and sign in

On the magpie service's Networking tab, add a domain for port 3430, for example magpie.example.com. Add a DNS A record pointing to your server and wait for HTTPS. See Domains for the steps.

Then copy the value of MAGPIE_WEB_KEY from the service's Variable tab, open https://magpie.example.com and paste the key where the page asks for it. Your browser stays signed in.

This key is Magpie's admin password. Anyone who has it can change every setting and see the provider keys you add. So:

• Don't give it to people who only need to call models. They need a gateway key, described below.
• Keep it out of screenshots, chat messages and repositories.
• If you think it has leaked, change it in Variable to a new random value (16 or more letters, digits or - . _ ~), save and restart the service.

Magpie's own docs recommend keeping the browser UI on your machine or a VPN. On a public domain, this key is the only thing protecting it, so guard it as above.

Set the public address

In Variable, add MAGPIE_PUBLIC_URL with the value https://magpie.example.com, save and restart. Magpie runs in a container and sees only the container's internal address; with this variable, the addresses and setup examples it shows use your domain.

Add providers

Add providers on the Providers page of the browser UI. Magpie has presets for Anthropic, OpenAI, Google Gemini, DeepSeek, Kimi, Zhipu GLM, Qwen, Mistral, xAI, OpenRouter and more, and accepts any OpenAI- or Anthropic-compatible URL. Enter the provider's API key, save, and check that its models appear in the list.

Model names in Magpie take the form provider/model, for example deepseek/deepseek-v4-pro. You can also create routing groups: a set of models that takes requests in order, in turn or by usage, and moves to the next when one fails. Agents use the group's name as the model.

Magpie can also use subscriptions such as Claude or ChatGPT as providers. Signing in to them on a server takes extra steps, described in Magpie's Docker docs. Read each provider's terms first: a personal subscription is usually for you alone, so don't share it with others through the gateway.

Hand out gateway keys

Magpie on a server only accepts requests that carry an enabled gateway key; others get a 401. In the browser UI, open Gateway → Gateway keys, create a key for each computer or person, and copy it. The full key is shown only when it's created.

Each key can have its own:

• Limits: tokens and estimated cost per day, week, month or in total;
• Models: for example only deepseek/*;
• State: if a key leaks, disable or rotate it without affecting other clients or rotating your provider keys.

Holders of a gateway key can open https://magpie.example.com/me, enter their key, and see their own limits, usage, models and ready-to-copy setup for Claude Code and Codex. They see nothing of other keys or providers.

Connect Claude Code

On your computer, set:

export ANTHROPIC_BASE_URL="https://magpie.example.com"
export ANTHROPIC_AUTH_TOKEN="your Magpie gateway key"
export ANTHROPIC_MODEL="deepseek/deepseek-v4-pro"
claude

ANTHROPIC_BASE_URL is the domain alone, without /v1; Claude Code adds /v1/messages itself. Set ANTHROPIC_MODEL to a model or routing group you see in Magpie, or switch with /model inside Claude Code. To also inspect logs, deploy, and roll back Zenavo services directly from Claude Code with MCP and Skills, see Deploy and debug Zenavo projects from Claude Code.

Connect Codex CLI

Codex CLI defines custom providers in ~/.codex/config.toml:

model = "deepseek/deepseek-v4-pro"
model_provider = "magpie"

[model_providers.magpie]
name = "magpie"
base_url = "https://magpie.example.com/v1"
model_catalog_url = "https://magpie.example.com/v1/codex/models"
env_key = "MAGPIE_API_KEY"
wire_api = "responses"
supports_websockets = false

Then run export MAGPIE_API_KEY="your gateway key" and start codex. Here base_url includes /v1, unlike Claude Code. model_catalog_url lets Codex read the models this key may use from Magpie.

For any other OpenAI-compatible web UI or client (such as self-hosted Open WebUI or LobeHub), use https://magpie.example.com/v1 as the base URL and a gateway key as the API key.

Backups and upgrades

The /config volume holds your provider API keys, subscription sign-ins and gateway keys, so protect its backups as you would the keys themselves.

In a maintenance window, stop the project, back up the volume from the magpie service's Backup & Restore tab, start the project again and download a copy to keep. Before upgrading, read Magpie's release notes, then back up before changing the image version.

FAQ

My agent gets a 401. The request has no gateway key, or the key is disabled. Magpie on a server doesn't accept the placeholder magpie key that a local install does. Also check that you used a gateway key, not MAGPIE_WEB_KEY.

Claude Code returns 404 or can't connect. Check whether ANTHROPIC_BASE_URL ends in an extra /v1.

A model doesn't exist or is refused (403). Use the provider/model form, and make sure the model is one this gateway key may use. Request https://magpie.example.com/v1/models with the key to list every model it may use.

Who sees my code? Requests still go to the providers you choose; running the gateway on your own server doesn't keep the data on it. Magpie has optional privacy masking that replaces keys, passwords and email addresses with placeholders before a request leaves; turn it on in Settings → Privacy. Magpie sends anonymous statistics once a day (no prompts, keys or usage), which you can turn off on the same page or with DO_NOT_TRACK=1 in Variable.

Is a small server enough? Magpie itself is light; the template recommends 512 MB of memory. The load comes from concurrent streaming requests, so watch memory and bandwidth when several people use it at once.

Start from the Magpie template: add a domain and keep the sign-in key safe, add providers, hand out gateway keys, then point Claude Code and Codex at it.