---
title: "Self-host the Magpie AI gateway: switch models freely in Claude Code, Codex and other agents"
description: "Deploy Magpie on your own server with Zenavo, manage providers such as DeepSeek, Kimi, Anthropic and OpenAI in one place, give each computer its own gateway key, then point Claude Code and Codex CLI at it."
date: 2026-11-12
language: en
url: https://zenavo.app/blog/self-host-magpie
---

# 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](https://usemagpie.ai) 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](https://zenavo.app/blog/self-host-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](https://docs.zenavo.app/servers/add-a-server) to Zenavo, then open the [Magpie template](https://zenavo.app/deploy?template=magpie), 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](https://docs.zenavo.app/networking/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](https://usemagpie.ai/docs/docker). 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:

```bash
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](https://zenavo.app/blog/claude-code-deploy-debug).

## Connect Codex CLI

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

```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](https://zenavo.app/blog/self-host-open-webui) or [LobeHub](https://zenavo.app/blog/self-host-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](https://zenavo.app/deploy?template=magpie): add a domain and keep the sign-in key safe, add providers, hand out gateway keys, then point Claude Code and Codex at it.