Skip to main content
AI tutorials

Manage AI Agent Models and Providers with Magpie

Learn how to install Magpie, connect model providers, switch models for tools such as Claude Code and Codex, save reusable profiles, and route OpenAI, Anthropic, and Gemini-compatible applications through its local gateway.

About 28 min read
Manage AI Agent Models and Providers with Magpie

What Magpie Does

Magpie provides one place to view and change the models used by AI agents installed on your computer. It is available as a menu bar application, a regular desktop window, a terminal user interface, and a command-line tool.

Instead of manually editing several JSON, TOML, YAML, and environment files, you can select an agent, choose a field, and assign a model. Magpie modifies only the relevant setting, preserving comments, ordering, and indentation where applicable. Its writes are atomic.

Magpie currently recognizes Claude Code, Codex, Gemini CLI, OpenCode, Pi, Goose, Cursor CLI, Copilot CLI, and Crush. Only agents that are installed or configured appear in its interface.

Key Features

  • Multiple interfaces: Use the desktop application, menu bar panel, terminal UI, or plain CLI.
  • Surgical configuration edits: Magpie changes the selected key without rewriting the rest of the agent configuration.
  • Unified local gateway: Agents can access models from multiple vendors through a single loopback endpoint.
  • API translation: The gateway supports OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Google Gemini-compatible requests, including streaming and tool calls.
  • Shared subscriptions: Existing Claude Code, Codex, and Copilot sign-ins can appear as providers for other agents.
  • Live model catalogs: Magpie fetches model lists from providers and supplements them with data from models.dev.
  • Provider presets: Presets are available for vendors and services including Anthropic, OpenAI, Gemini, DeepSeek, Kimi, GLM, MiniMax, Qwen, Mistral, Groq, xAI, OpenRouter, Together, Ollama, and LM Studio.
  • Profiles: Save all current agent settings under a name and restore them together later.
  • Small native builds: The desktop build uses the operating system webview rather than bundling a browser runtime.

Install Magpie

Install a Prebuilt Release

Download the desktop application for macOS, Windows, or Linux from usemagpie.ai. You can also run the installation script:

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

On Linux, the installer selects the desktop application when WebKitGTK 4.1 is available and otherwise installs the command-line build. macOS releases are signed and notarized. Windows and Linux builds are not currently signed, so Windows SmartScreen may display a warning on first launch.

Magpie checks for updates in the background. The desktop application installs an update when it restarts or quits, while terminal users can update explicitly:

magpie update

Install from Go Source

If you have Go installed, install the latest version directly:

go install github.com/yetone/magpie@latest

Build the Repository Locally

The repository provides several Make targets:

make build            # Desktop application binary
make app              # macOS menu bar application
make cli              # Terminal-only build without cgo
make release          # Native app and cross-platform CLI builds
make release-windows  # Windows amd64 and arm64 application builds
make release-linux    # Linux application for the current architecture

Building the Linux desktop application requires libgtk-3-dev and libwebkit2gtk-4.1-dev. A plain Go build must use the gtk3 build tag. Windows uses the WebView2 runtime included with the operating system.

Open the Interface

Choose the interface that fits your workflow:

magpie          # Open a window and the menu bar icon
magpie tray     # Run only the menu bar icon
magpie tui      # Open the terminal interface
magpie ls       # List detected agents and current settings

The desktop interface lets you click any current value to open a filtered picker. Type to search or enter a custom value, and press esc to close the picker.

In the terminal interface, use the arrow keys to select an agent and field, press Enter to open its picker, and type to filter available choices. Press q to quit.

Add a Model Provider

Inspect Available Presets

Begin by listing the providers Magpie already knows:

magpie presets

Presets are grouped into vendors, relays, and local services. A hosted preset usually needs only an API key:

magpie provider add deepseek sk-…

Local providers such as Ollama do not require a key:

magpie provider add ollama

Magpie does not read provider keys from your shell environment. Add them through the application or provider commands instead.

Add a Custom OpenAI-Compatible Provider

A custom provider can be configured with a name, base URL, key, and explicit model list:

magpie provider add "My Relay" url=https://relay.example.com/v1 key=sk-… models=gpt-5.5,claude-sonnet-5

Custom providers may use url= for an OpenAI-compatible base, anthropic= for an Anthropic-compatible base, or both. Use responses= when the provider has a separate Responses endpoint. The optional catalog= argument can borrow metadata from a models.dev provider.

Inspect and Test Providers

Use these commands to review providers, refresh model lists, test APIs, rotate keys, or remove an entry:

magpie providers
magpie provider deepseek
magpie provider models deepseek
magpie provider test deepseek
magpie provider key deepseek sk-…
magpie provider rm deepseek
magpie models

magpie provider test makes one small request per supported API and reports latency. In the desktop application, the Providers tab offers equivalent controls for changing keys, selecting exposed models, testing providers, and assigning their models to agents.

Switch Agent Models

Models exposed through the gateway use the form provider/model. Native agent models can also be selected by their usual names.

Basic CLI Examples

magpie claude opus
magpie codex gpt-5.6-sol
magpie codex effort high
magpie codex xhigh
magpie codex deepseek/deepseek-chat
magpie claude moonshot/kimi-k2.5
magpie gemini auth api-key
magpie opencode anthropic/claude-sonnet-5
magpie oc small anthropic/claude-haiku-4-5

Agent names accept prefixes such as cc, oc, and gem. Provider-scoped agents including OpenCode, Pi, Goose, and Crush use provider/model identifiers.

Configure Claude Code Tiers

Claude Code can assign separate models to tiers such as opus, sonnet, haiku, and fable. For example, assign a DeepSeek model only to the haiku tier:

magpie claude haiku deepseek/deepseek-v4-flash

Clear that tier-specific selection to return it to Claude Code's main model:

magpie claude haiku ""

When a gateway model is selected, Magpie manages the Anthropic base URL, token, and model variables in Claude Code's settings.json. Selecting a native model removes Magpie's gateway settings and restores the previous values.

Restart Agents After Switching

Agents read their configuration when they start. An already-running session continues using its previous model until you start a new session.

This is especially important for Codex, which reads its model catalog at startup and must be restarted after a switch.

Save and Restore Profiles

A profile captures the current settings of every detected agent. This is useful for maintaining separate configurations for work, experimentation, local inference, or cost-sensitive tasks.

magpie save work
magpie use work
magpie profiles
magpie rm work

In the desktop application, profiles appear as chips at the bottom of the main view. Click a chip to apply it, use its delete control to remove it, or select + save current to create a profile.

In the terminal interface, press s to save the current setup and p to apply or delete a profile.

Use Signed-In Agents as Providers

Magpie can expose existing Claude Code, Codex, and Copilot subscriptions as providers. After you sign in through the original agent, its available models appear in magpie providers and in other agents' model pickers.

  • Claude Code models use identifiers such as claude/claude-sonnet-5.
  • Codex subscription models use identifiers such as codex/gpt-5.5.
  • Copilot models use identifiers such as copilot/claude-sonnet-4.5.

Magpie reads the agent's existing credentials when needed and does not copy them into its own provider store. If the original agent rotates a token, Magpie follows that agent's refresh process and writes the rotated token where the agent expects it. Signing out removes the corresponding provider.

Claude subscriptions require the genuine local claude binary to be installed and signed in. Magpie runs that binary and bridges caller tools into the live turn over MCP. Gemini CLI Google login support is planned but is not currently available as a shared provider.

Connect Other Applications to the Gateway

Magpie's gateway listens on 127.0.0.1:3425 by default and starts with the application. To run only the gateway, use:

magpie serve

Set MAGPIE_ADDR to change the listening address. The default loopback binding keeps the gateway local to your computer.

Supported API Endpoints

  • /v1/chat/completions for OpenAI Chat Completions.
  • /v1/responses for OpenAI Responses.
  • /v1/messages for Anthropic Messages.
  • /v1/messages/count_tokens for Anthropic token counting.
  • /v1beta/models/{model}:generateContent for Gemini generation, with streaming and token-counting variants.
  • /v1/models and /v1beta/models for the model catalog.

The API key can be the literal value magpie; any value works because the gateway listens on loopback by default. Always specify models as provider/model.

OpenAI-Compatible Environment

export OPENAI_BASE_URL=http://127.0.0.1:3425/v1
export OPENAI_API_KEY=magpie

Anthropic-Compatible Environment

export ANTHROPIC_BASE_URL=http://127.0.0.1:3425
export ANTHROPIC_API_KEY=magpie

Gemini-Compatible Environment

export GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:3425
export GEMINI_API_KEY=magpie

The desktop application's Gateway tab provides copyable settings and snippets for shell, curl, Python, and Node. It also displays model IDs and recent calls.

Refresh Model Catalogs

Magpie fetches real model lists from configured providers. The models.dev catalog supplies names, reasoning levels, and fallback lists for providers that do not publish their own catalogs.

Run a full synchronization when you want to refresh models.dev data and all live provider lists:

magpie sync

In the terminal interface, press S for the same action. You can also refresh only one provider with magpie provider models PROVIDER.

Import Provider Links Safely

Vendors and relays can distribute prefilled provider definitions using import links. Magpie displays the proposed provider name, endpoints, destination hosts, and models before saving anything.

magpie import 'magpie://import?preset=deepseek&key=sk-…'

A custom relay link can include separate OpenAI and Anthropic endpoints:

magpie://import?name=Acme%20Relay&chat=https://api.acme.example/v1&anthropic=https://api.acme.example&key=sk-…&models=gpt-5.5,claude-sonnet-5

Nothing is stored until the user confirms the import. Web pages can use https://usemagpie.ai/import# followed by the same parameters. Because the values remain in the URL fragment, browsers do not send them to the website's server. See the Magpie import guide for the full parameter reference and link builder.

Advanced Tips

Limit Exposed Models

You do not have to expose every model returned by a provider. Select only the models you want to appear in agent pickers. This keeps large catalogs manageable and helps prevent accidental model selection.

Inspect Gateway Translation

Enable debug logging to see what the gateway translates:

MAGPIE_DEBUG=1 magpie serve

Requests pass through directly when a vendor already speaks the caller's API. Otherwise, Magpie translates the request and response while preserving supported streaming, tool-call, and reasoning behavior.

Know Where Data Is Stored

  • ~/.config/magpie/profiles.json stores saved profiles.
  • ~/.config/magpie/providers.json stores providers and their keys with file mode 0600.
  • ~/.config/magpie/stash.json stores replaced values so they can be restored.
  • ~/.cache/magpie/models.json stores the models.dev catalog.
  • ~/.cache/magpie/models/<provider>.json stores model lists fetched from providers.

Magpie respects XDG_CONFIG_HOME and XDG_CACHE_HOME.

Use an Isolated Development Home

Contributors can run the development build without touching their normal agent configurations:

HOME=/tmp/magpie-home XDG_CONFIG_HOME=/tmp/magpie-home/.config make dev

make dev serves the interface directly from internal/gui/assets and reloads it when frontend files change. Its gateway uses DEV_ADDR, defaulting to 127.0.0.1:3426, so it can run beside a normal Magpie instance. Set MAGPIE_THEME=light or MAGPIE_THEME=dark to force a palette.

Conclusion

Magpie replaces scattered model configuration with one consistent workflow. After installing it, add a provider or use an existing agent subscription, select models for each agent, and save useful combinations as profiles. Its local gateway also lets other OpenAI-, Anthropic-, and Gemini-compatible tools share the same provider catalog without storing vendor credentials in every application.