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

# magpie

> Configure a GravitexAI multi-protocol gateway with magpie, using WorkBuddy as an example

> [!NOTE]
>
> For Codex Desktop setup on macOS and Windows, see [Codex Desktop](https://docs.gravitex.ai/en/integrations/codex-desktop.md)。

## 1. Overview

**magpie** is an open-source local model gateway and Agent configuration manager. Reuse provider settings across clients and translate between Chat Completions, Responses, and Anthropic Messages.

This guide uses **WorkBuddy**: it sends Chat Completions requests to local magpie, which converts and forwards them to GravitexAI according to the model and upstream settings.

| Connection | Address or protocol |
| - | - |
| WorkBuddy → magpie | `http://127.0.0.1:3425/v1/chat/completions` |
| magpie → GravitexAI GPT | `/v1/responses` |
| magpie → GravitexAI Claude | `/v1/messages` |
| magpie → Chat Completions models | `/v1/chat/completions` |

> [!NOTE]
>
> If your model works directly in WorkBuddy, use the [direct connection guide](https://docs.gravitex.ai/en/integrations/workbuddy.md). Use magpie when protocol conversion is needed. Image connectors are covered in [WorkBuddy-Image Generation](https://docs.gravitex.ai/en/integrations/workbuddy-image-generation.md).

## 2. Prerequisites

* WorkBuddy installed and launched at least once.
* A key from the [GravitexAI Console](https://maas.gravitex.ai/#/api-keys).
* Available model IDs and supported routes confirmed in the [Model Catalog](https://maas.gravitex.ai/#/api-models).
* WorkBuddy and magpie on the same computer. The gateway uses port `3425` by default.

## 3. Install magpie

> [tab] macOS
>
> Use the official installer:
>
> ```bash theme={null}
> curl -fsSL https://usemagpie.ai/install.sh | sh
> ```
>
> Or download an Apple Silicon/Intel package from [magpie](https://usemagpie.ai/). Open the app and verify:
>
> ```bash theme={null}
> magpie --version
> magpie ls
> ```
>
> If the command is missing, reopen the terminal or add \~/.local/bin to your shell PATH.

> [tab] Windows
>
> Download the correct architecture from the [website](https://usemagpie.ai/) or [Releases](https://github.com/yetone/magpie/releases).
>
> | Package | Interface |
> | - | - |
> | magpie-windows-amd64.exe / magpie-windows-arm64.exe | Desktop and tray |
> | magpie-cli-windows-amd64.exe / magpie-cli-windows-arm64.exe | CLI only |
>
> Open the desktop version to run the gateway. Add its folder to PATH and use magpie.exe in PowerShell, or call the executable by its actual path. Replace magpie with magpie.exe in the commands below as appropriate.

> [!NOTE]
>
> This guide uses only a GravitexAI API key. Importing Claude, ChatGPT, or other subscription credentials is unnecessary.

## 4. Configure the GravitexAI provider

### Step 1: Add three protocol endpoints

On macOS, replace the placeholder key and run:

```bash theme={null}
magpie provider add gravitex \
  url=https://api.gravitex.ai/v1 \
  responses=https://api.gravitex.ai/v1 \
  anthropic=https://api.gravitex.ai \
  key=sk-your-api-key \
  name=GravitexAI
```

Single-line PowerShell equivalent:

```powershell theme={null}
magpie.exe provider add gravitex url=https://api.gravitex.ai/v1 responses=https://api.gravitex.ai/v1 anthropic=https://api.gravitex.ai key=sk-your-api-key name=GravitexAI
```

| Field | Value | Purpose |
| - | - | - |
| `gravitex` | Provider ID | Reference used in later commands |
| `url=` | `https://api.gravitex.ai/v1` | Chat Completions base |
| `responses=` | `https://api.gravitex.ai/v1` | Responses base |
| `anthropic=` | `https://api.gravitex.ai` | Anthropic Messages base |
| `key=` | GravitexAI API key | Upstream authentication |
| `name=` | `GravitexAI` | Display name |

> [!WARNING]
>
> Enter base URLs. url= and responses= include /v1 but not /chat/completions or /responses. anthropic= has no /v1; magpie adds the Messages route.

Alternatively, edit GravitexAI on the **Providers** page. In **Base URL**, enter the **OpenAI compatible**, **OpenAI Responses**, and **Anthropic compatible** endpoints, add your key, and click **Save**. The Chinese-interface screenshot shows the Responses URL.

![Configure the GravitexAI Responses endpoint in magpie](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/magpie-provider.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=9eb8729dedb6ce51f789ff58a5c961b7)

> [!NOTE]
>
> The screenshot uses provider ID gravitexai, while the commands use gravitex. Use your actual ID consistently. With the screenshot's ID, model names are `gravitexai/model-id`.

### Step 2: Extend an existing provider

If gravitex already exists, add the missing routes instead of creating it again:

```bash theme={null}
magpie provider set gravitex responses=https://api.gravitex.ai/v1 anthropic=https://api.gravitex.ai
```

> [!NOTE]
>
> For GPT models needing both tools and reasoning, configure Responses. If you see `Function tools with reasoning_effort are not supported`, check this route before disabling reasoning.

### Step 3: Test and select models

```bash theme={null}
magpie provider test gravitex
magpie models workbuddy
```

If a desired model is missing, expose it explicitly:

```bash theme={null}
magpie provider models gravitex +gpt-6-sol +claude-sonnet-5-5 +deepseek-v4-pro
```

IDs are examples; use models available to your account. Provider tests send upstream requests and may incur small API charges.

## 5. WorkBuddy example

### Step 1: Identify the client and configuration directory

Run `magpie ls` to confirm the correct client is detected.

| Client | Default configuration |
| - | - |
| WorkBuddy China | `~/.workbuddy/models.json` |
| WorkBuddy AI international | `~/.workbuddy-ai/models.json` |
| CodeBuddy Code | `~/.codebuddy/models.json` and `settings.json` |

> [!NOTE]
>
> The following uses WorkBuddy China. If WORKBUDDY\_CONFIG\_DIR is set, use that directory. On Windows, \~ means the current user's home.

### Step 2: Quit and back up

Fully quit WorkBuddy: Cmd+Q on macOS, or exit from the Windows tray and check that the process stops.

> [tab] macOS
>
> ```bash theme={null}
> cp ~/.workbuddy/models.json ~/.workbuddy/models.json.bak-$(date +%Y%m%d-%H%M%S)
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $workbuddyModels = Join-Path $HOME '.workbuddy/models.json'
> Copy-Item $workbuddyModels "$workbuddyModels.bak-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
> ```

### Step 3: Select a model and connect

Choose one available model:

```bash Claude theme={null}
magpie workbuddy gravitex/claude-sonnet-5-5
```

```bash GPT theme={null}
magpie workbuddy gravitex/gpt-6-sol
```

Run one of the commands, not both. Model names use provider-id/model-id. magpie writes its connection settings into WorkBuddy's model file.

In the desktop app, you can instead open **Agent**, find WorkBuddy, enable its connection switch, and select a GravitexAI model. The screenshot shows the layout; WorkBuddy is outside the visible portion, so continue through the list.

![magpie Agent switches and model selectors](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/magpie-agents.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=cd688814d6f5bf73982985cabbd48919)

### Step 4: Reopen WorkBuddy and verify

1. Keep magpie running.
2. Reopen WorkBuddy.
3. Select a magpie `gravitex/…` model in the model picker.
4. Create a task and send a short message to confirm a reply.
5. Use a test folder for a simple file/tool task to check tool calls and reasoning.

The example uses gpt-6-luna and receives a greeting reply. The composer shows the selected model. After basic chat works, test tools too.

![WorkBuddy using gpt-6-luna with a successful response](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/magpie-workbuddy-chat.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=3a53795d7e0d5ac43e30ddc062b490e7)

> [!TIP]
>
> Fully restart WorkBuddy after connecting it or changing its model list. Changing only magpie's upstream routing usually does not require rewriting the client model file; send a new request to verify.

## 6. Verification and troubleshooting

### Check the local gateway

> [tab] macOS
>
> ```bash theme={null}
> lsof -nP -iTCP:3425 -sTCP:LISTEN
> ```
>
> If nothing is listening, open magpie:
>
> ```bash theme={null}
> open -a magpie
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> Get-NetTCPConnection -LocalPort 3425 -State Listen
> ```
>
> If the port is not listening, open the downloaded desktop program.

### Check tools and reasoning

If chat works but tools return 400, check whether the error mentions tools and reasoning\_effort. Confirm responses=[https://api.gravitex.ai/v1](https://api.gravitex.ai/v1) and model support for Responses.

A model appearing in the list is insufficient: verify both a reply and a tool task. If a reasoning model returns HTTP 200 with empty text, check whether its output budget is too small.

> [accordion] WorkBuddy model list did not change
>
> Fully quit and reopen WorkBuddy. Check that you connected workbuddy (China), rather than the international edition or CodeBuddy Code. Use magpie ls to confirm the client and directory.

> [accordion] magpie models cannot connect
>
> Check that magpie is running and port 3425 is listening. Ensure a proxy is not intercepting 127.0.0.1. Both the local gateway and upstream GravitexAI must be reachable.

> [accordion] Claude returns 404
>
> Set anthropic=[https://api.gravitex.ai](https://api.gravitex.ai) without /v1. Configuring only url= does not establish the native Messages route.

> [accordion] GPT tools plus reasoning returns 400
>
> Add responses=[https://api.gravitex.ai/v1](https://api.gravitex.ai/v1) and check model/account support. Avoid forwarding the combination to an incompatible Chat Completions route.

> [accordion] 401 / 403
>
> Distinguish gateway credentials from the GravitexAI upstream key. Update an upstream key with magpie provider key gravitex sk-new-api-key and retest. Manual local requests require the gateway's credential, not the upstream key.

> [accordion] A model is missing
>
> Confirm account access, then run magpie provider models gravitex +model-id. Reconnect WorkBuddy and restart the client if necessary.

## 7. Rollback and maintenance

### Disconnect WorkBuddy

```bash theme={null}
magpie workbuddy default
```

Fully restart WorkBuddy afterward. Alternatively, restore models.json from your backup while the client is fully closed.

### Start at login

```bash theme={null}
magpie autostart on
```

The gateway must remain running for magpie models. Keep working direct-connection models as a fallback.

## 8. Resources

* [magpie website](https://usemagpie.ai/)
* [yetone/magpie](https://github.com/yetone/magpie)
* [Getting started](https://usemagpie.ai/docs/start)
* [Official Reference](https://github.com/yetone/magpie/blob/main/docs/reference.md)
* [WorkBuddy direct configuration](https://docs.gravitex.ai/en/integrations/workbuddy.md)
* [GravitexAI keys](https://maas.gravitex.ai/#/api-keys)


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