Skip to main content
For Codex Desktop setup on macOS and Windows, see Codex Desktopใ€‚

โ€‹
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.
If your model works directly in WorkBuddy, use the direct connection guide. Use magpie when protocol conversion is needed. Image connectors are covered in WorkBuddy-Image Generation.

โ€‹
2. Prerequisites

  • WorkBuddy installed and launched at least once.
  • A key from the GravitexAI Console.
  • Available model IDs and supported routes confirmed in the Model Catalog.
  • WorkBuddy and magpie on the same computer. The gateway uses port 3425 by default.

โ€‹
3. Install magpie

Use the official installer:
Or download an Apple Silicon/Intel package from magpie. Open the app and verify:
If the command is missing, reopen the terminal or add ~/.local/bin to your shell PATH.
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:
Single-line PowerShell equivalent:
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
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:
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

If a desired model is missing, expose it explicitly:
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.
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.

โ€‹
Step 3: Select a model and connect

Choose one available model:
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

โ€‹
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
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

If nothing is listening, open magpie:

โ€‹
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 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.
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.
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.
Set anthropic=https://api.gravitex.ai without /v1. Configuring only url= does not establish the native Messages route.
Add responses=https://api.gravitex.ai/v1 and check model/account support. Avoid forwarding the combination to an incompatible Chat Completions route.
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.
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

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

โ€‹
Start at login

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

โ€‹
8. Resources