> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Magpie

> Connect Magpie to APIYI through the desktop interface, configure models, API URLs, and keys for Codex and Claude Code, and troubleshoot with CLI examples

## How Magpie connects to APIYI

Magpie is an open-source application for managing models and providers for AI coding tools. After adding APIYI to Magpie, you can choose models for Codex, Claude Code, and other tools in one interface. Magpie writes the settings to each tool's configuration files.

Requests pass through a local gateway before reaching APIYI:

```text theme={null}
Coding tool → Magpie gateway → APIYI → Model
```

Enter the APIYI URL and your real API key in Magpie's **provider settings**. Magpie connects your coding tools to its local gateway, which listens on `127.0.0.1:3425` by default. Keep Magpie running while using the tools.

Project: `github.com/yetone/magpie`; official getting started guide: `usemagpie.ai/docs/start`.

## Before you start

1. Download the desktop app for macOS, Windows, or Linux from `usemagpie.ai`, then install and open it.
2. Install the coding tool you want to use. See the installation sections of the [Codex configuration guide](https://docs.apiyi.com/en/scenarios/programming/codex-cli.md) or [Claude Code configuration guide](https://docs.apiyi.com/en/scenarios/programming/claude-code.md).
3. Prepare API keys on the [APIYI token page](https://api.apiyi.com/token). Confirm that your account has an available balance and the tokens can access your selected models.

This guide covers two provider entries: **APIYI** and **APIYI Claude**. If you use only one coding tool, configure just its corresponding entry. To create both entries, use **two different tokens**: a token with access to GPT models for the first entry, and a token in the `ClaudeCode` group for the second. Magpie treats configurations that use the same key on the same host as duplicate providers.

> [!NOTE]
>
> Magpie does not automatically read API key environment variables from your terminal. Paste your key into the provider form, or add it with the CLI commands below.

## Configure through the desktop interface

### Configure the provider for Codex

**1. Add a custom provider**

Open **Providers → Add provider → Custom provider** and enter:

| Field | Value |
| - | - |
| Name | `APIYI` |
| Primary protocol | **OpenAI compatible** |
| Base URL | `https://api.apiyi.com/v1` |
| API key | Your APIYI token for GPT models |

End the URL at `/v1`. Magpie appends the request path, so do not enter the full `/chat/completions` path.

**2. Add a Responses endpoint for GPT models**

Expand **More endpoints** and set **Responses URL** to `https://api.apiyi.com/v1`.

This guide uses `gpt-5.4`, which supports both Chat Completions and Responses on APIYI. Codex can use the Responses endpoint when accessing this model through Magpie.

Only configure an endpoint when APIYI supports that protocol for the selected model. Responses support in Magpie's local gateway does not mean every model on APIYI supports native Responses.

**3. Fetch and select a model**

Click **Fetch models**, select `gpt-5.4` from the model list, and save the provider.

Select only this model for the initial setup. Before adding other GPT models, confirm that they support the same endpoints on APIYI. Do not add image, embedding, or other non-chat models to your coding tools' model lists.

If the model you need is missing from the list, add its exact model ID manually under **Models**. Enter `gpt-5.4` in the provider's model field without the `apiyi/` prefix.

### Configure the provider for Claude Code

Add another **Custom provider** using a different token from the `ClaudeCode` group:

| Field | Value |
| - | - |
| Name | `APIYI Claude` |
| Primary protocol | **Anthropic compatible** |
| Base URL | `https://api.apiyi.com` |
| API key | A different APIYI token from the `ClaudeCode` group |
| Models | `claude-sonnet-4-6` |

The URL here **does not include `/v1`**. Magpie appends `/v1/messages`. After fetching models, select only the Claude model you plan to use. You can also enter `claude-sonnet-4-6` manually, then save.

> [!TIP]
>
> Separate provider entries let you manage models, protocols, and token groups independently. For details about the `ClaudeCode` group, see [Token groups](https://docs.apiyi.com/en/faq/groups-explained.md).

### Select a model for each coding tool

1. Open **Agents** and find your installed **Codex** or **Claude Code** tool.
2. Click the tool's current model, then find and select the model under the provider you just added: **APIYI → gpt-5.4** for Codex, or **APIYI Claude → claude-sonnet-4-6** for Claude Code.
3. Close the tool's old session, restart it, and open a new session so it reads the configuration written by Magpie.

Magpie identifies models internally as `provider-id/model-id`, such as `apiyi/gpt-5.4`. The raw model ID entered in the provider form and the full identifier selected for an agent serve different purposes.

> [!NOTE]
>
> Magpie writes the API settings for tools it manages. When troubleshooting, also check existing environment variables, project settings, and other configuration managers to make sure they are not restoring a previous service URL.

## Verify the connection

Run a test on the provider page first, then send a short request from your coding tool, for example:

```text theme={null}
Reply with only: Connection successful.
```

After receiving a reply, check Magpie's request or usage records and the call logs in the [APIYI console](https://api.apiyi.com). Confirm that the request used the intended model and provider. Then ask the tool to explain a small file in your project to verify your everyday coding workflow.

**Fetching models successfully only confirms that the model list endpoint is reachable.** Chat requests also require a matching model, token permissions, and request protocol. Provider tests send a small number of real API requests, which are billed according to model usage.

## Configure through the CLI

If you prefer the terminal, use the following commands instead of adding providers through the interface. First, confirm that the `magpie` command is installed and keep the desktop app running.

> [!NOTE]
>
> If you have already created the providers in the interface, do not run `provider add` again. Run `magpie providers` to check their actual provider IDs, then substitute those IDs in the test or model-selection commands. IDs created through the interface are generated from provider names; `id=` in a command requests a particular ID. If an ID is already taken, Magpie may add a suffix, so check the actual IDs after adding providers through the CLI too.

### Add the two providers

Replace `sk-your-api-key` in the first command with your token for GPT models:

```bash theme={null}
magpie provider add APIYI id=apiyi url=https://api.apiyi.com/v1 responses=https://api.apiyi.com/v1 key=sk-your-api-key models=gpt-5.4
```

Replace `sk-your-api-key` in the second command with a **different** token from the `ClaudeCode` group:

```bash theme={null}
magpie provider add "APIYI Claude" id=apiyi-claude anthropic=https://api.apiyi.com key=sk-your-api-key models=claude-sonnet-4-6
```

### List models and connect the tools

```bash theme={null}
magpie providers
magpie models
magpie codex model apiyi/gpt-5.4
magpie claude model apiyi-claude/claude-sonnet-4-6
```

Run only the command for the tool you have installed and want to configure, then start a new session in that tool. These commands update configuration; the Magpie gateway must still be running when you use the tools.

### Test the upstream providers and local gateway

```bash theme={null}
magpie provider test apiyi
magpie provider test apiyi-claude
magpie healthcheck
```

`provider test` sends a small number of real requests to the configured upstream endpoints. `healthcheck` only checks the local gateway, so it cannot by itself confirm that model requests to APIYI work.

## Troubleshooting

> **Authentication fails with 401 or 403**
>
> Check that the API key saved in the Magpie provider is complete and valid, your APIYI account has an available balance, and the token can access the target model. Use a token from the `ClaudeCode` group for the Claude Code configuration. Changing terminal environment variables does not automatically update a key already saved in Magpie; edit and save the provider instead.

> **Requests return 404 or an endpoint-not-found error**
>
> Check the URL for the selected protocol: use `https://api.apiyi.com/v1` for OpenAI compatible and Responses, and `https://api.apiyi.com` for Anthropic compatible. Do not append the full request path. Confirm that the target model supports the endpoint, and do not configure a Responses endpoint for a model that only supports Chat Completions.

> **The model list loads, but the model is missing from Agents**
>
> Check that the model is selected and saved in the provider, then check the agent's own list of visible models. Run `magpie models` to see the models currently exposed by Magpie. When adding a model manually, check its raw model ID; when selecting it for a tool, check the provider prefix and ID.

> **Adding the second provider produces a duplicate warning**
>
> Magpie uses information such as the host and key to detect duplicate providers. The two entries in this guide require two different APIYI tokens. Changing only the provider name or protocol may still result in a duplicate warning.

> **A tool is missing from Agents, or a new model still uses the old configuration**
>
> Confirm that the tool is installed, then reopen Magpie to check whether it is detected. After selecting a model, start a new session in the tool. Check whether existing environment variables, project settings, or other configuration managers are overriding the configuration. See the corresponding guide on this site for tool installation instructions.

> **Coding tools cannot connect after Magpie is closed**
>
> Your coding tools now connect to the local gateway. Closing Magpie stops forwarding if no other gateway process is running. Reopen Magpie, then run `magpie healthcheck` to check whether the local gateway is online.

## Model selection and related resources

The model IDs in this guide demonstrate the configuration process. Confirm endpoint support and token permissions before adding other models. Current model recommendations and prices are maintained on the following pages.

> **[Model recommendations](https://docs.apiyi.com/en/api-capabilities/model-info.md)**
>
> Choose models for your coding needs and review usage recommendations.

> **[Model prices](https://docs.apiyi.com/en/models/index.md)**
>
> View current APIYI model prices and available models.

> **[Codex configuration guide](https://docs.apiyi.com/en/scenarios/programming/codex-cli.md)**
>
> Find tool installation, model configuration, and usage instructions.

> **[Claude Code configuration guide](https://docs.apiyi.com/en/scenarios/programming/claude-code.md)**
>
> Review installation, token groups, and troubleshooting.

Official configuration reference: `github.com/yetone/magpie/blob/main/docs/reference.md`. The configuration steps in this guide were checked against the project documentation and source code. Verify model listing, streaming, and tool calling with actual requests using your selected model and protocol.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.