Guide · Open source

How to use magpie: set up models for each AI coding agent

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

magpie is an open-source app from yetone that gives your AI coding agents one place to choose their models. It runs a local gateway on your computer, so you can point agents such as Claude Code or Codex at it and pick which provider or model each one uses. This guide shows you how to install it, add a provider, assign models to agents, and turn on quota fallback and prompt masking.

magpieyetone/magpie · ★ 28.2k · MIT Install options & downloads

Quick start

1Install magpie. Download the app from usemagpie.ai or run the install script, or install with go install github.com/yetone/magpie@latest.
2Add a provider. Open Providers, choose Add provider, then pick a preset and paste your key or sign in with a subscription.
3Pick a model for each agent. On the Agents page, choose the model for each agent, then start a new session.
4Create a routing group if you want fallback. Add a group with several models so a request can move on when a quota runs out. Point the agent at the group.
5Turn on masking if needed. Go to Settings → Privacy and enable masking, which is off by default.

What magpie does

Each AI coding agent keeps its model setting in its own config file, with its own keys and base URLs. magpie puts those settings behind one app and one local gateway at 127.0.0.1:3425.

You can pick any model for any agent from one list. magpie edits the key that matters in the agent's own config and leaves the rest of the file as it was.

Pick any model for any agent from one list
Use one provider across agents: an API key, a local model, or a supported subscription you are signed in to
Move a request to another account or model when a quota runs out, if you set up a routing group
Mask keys, passwords and emails in prompts, if you turn masking on

Install magpie on macOS, Windows or Linux

Download the app from usemagpie.ai, or install from the terminal with the install script. The source lists no other prerequisites.

You can also install with Go. The source notes that Mac builds are signed and notarised and that every build updates itself. Behind a firewall, the install script accepts --proxy or --mirror.

Download from https://usemagpie.ai
Install script (see code block)
Go users can run go install github.com/yetone/magpie@latest
Docker and Termux are also listed as supported

curl -fsSL https://usemagpie.ai/install.sh | sh

Add a provider and pick a model in the app

Open magpie and go to Providers, then Add provider. Choose a preset and paste a key, or sign in with a subscription.

Next, open the Agents page and pick a model for each agent. Start a new session and it uses the new model.

Go to Providers → Add provider
Pick a preset and paste your key, or sign in with a subscription
On the Agents page, choose a model for each agent
Start a new session to use the change

Set up models from the terminal

If you prefer the command line, magpie has commands for providers, agents, routing groups, profiles, quota and a terminal UI. The examples below come from the README.

A routing group lets an agent fail over between models or subscriptions. With one account and no group, the error reaches the agent instead.

magpie provider add takes a preset name and your key
magpie claude or magpie codex sets the model for that agent
magpie save and magpie use manage profiles
magpie quota shows what is left on each plan
magpie tui opens the terminal interface

magpie provider add deepseek sk-…
magpie claude deepseek/deepseek-v4-pro
magpie codex moonshot/kimi-k2.5
magpie group add "Opus anywhere" models=claude/claude-opus-5-5,copilot/claude-opus-5.5 routing=smart
magpie claude group/opus-anywhere
magpie save work && magpie use work
magpie quota
magpie tui

Control which accounts magpie reads

magpie finds subscriptions by reading the sign-in files of your agents, such as Claude Code's and Codex's files and the Keychain. If you do not want that, turn off Settings → Privacy → Subscription accounts, or run the command below. API-key providers work either way.

The MAGPIE_NO_ACCOUNTS=1 variable turns discovery off for one run without changing the saved setting.

Settings → Privacy → Subscription accounts turns discovery off
magpie accounts discovery off turns it off; on turns it back on
MAGPIE_NO_ACCOUNTS=1 turns it off for a single run

magpie accounts discovery off

Turn on prompt masking

Masking is off by default. Turn it on in Settings → Privacy. When it is on, keys, passwords and emails in a prompt are masked on your computer before the request leaves it, and put back in the reply.

Masking is a setting you choose to enable. The source does not describe how complete it is, so test it with your own kinds of data.

Open Settings → Privacy
Turn on masking (off by default)

Use magpie with other tools that accept a base URL

The source says any other tool that takes a base URL can use the gateway. Set the base URL and key variables to point at the local gateway. The key value magpie is a placeholder used in the README examples.

OpenAI-style tools: OPENAI_BASE_URL and OPENAI_API_KEY
Anthropic-style tools: ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY
Gemini-style tools: GOOGLE_GEMINI_BASE_URL and GEMINI_API_KEY

export OPENAI_BASE_URL=http://127.0.0.1:3425/v1     OPENAI_API_KEY=magpie
export ANTHROPIC_BASE_URL=http://127.0.0.1:3425     ANTHROPIC_API_KEY=magpie
export GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:3425 GEMINI_API_KEY=magpie

What people use it for

Running Claude Code on DeepSeek while Codex runs on Kimi, managed from one menu bar app
Keeping a work session going by failing over between accounts when one quota runs out
Switching the model for an agent without hand-editing its config files
Saving named profiles such as Budget or Focus and switching all agents at once
Masking keys, passwords or emails in prompts before they leave your computer

Frequently asked questions

Is magpie free and open source?

magpie is released under the MIT licence, and its source is written in Go. The source does not describe pricing for any providers you connect, so check those separately.

How do I install magpie?

Download the app from usemagpie.ai, or run the install script curl -fsSL https://usemagpie.ai/install.sh | sh. You can also run go install github.com/yetone/magpie@latest or use the Docker image.

Does magpie need any prerequisites?

The source lists no prerequisites for the app download. It runs on macOS, Windows and Linux, in Docker, and on Termux.

Do I need magpie if I only use one agent?

Not necessarily. The README says that if you use one agent on its vendor's own plan and that is enough, you do not need magpie.

Why does magpie read my agent sign-in files?

magpie discovers subscriptions by reading the sign-in files of agents such as Claude Code and Codex, and the Keychain. You can turn this off in Settings → Privacy or with magpie accounts discovery off. API-key providers work either way.

What happens when a quota runs out?

If you have several accounts for a provider or a routing group with other models, magpie can move the request on so the agent does not see an error. With one account and no group, the error reaches the agent.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

magpie suits people who use several AI coding agents, providers or accounts and want to manage their models in one place. It is less useful if you use a single agent on its vendor's plan, and it may not suit anyone who does not want a background local gateway or an app that reads existing agent sign-ins.

Install options & downloads