### magpie daemon commands for service management

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Commands to install, check status, restart, stop/start, uninstall, and toggle web serving for the magpie background service. The install command writes the service and starts it; run it again to pick up a new PATH or proxy. The web on command makes the service serve the browser page as well.

```sh
magpie daemon install    # write the service and start it; again, to take a new PATH or proxy
magpie daemon status     # running or not, its pid, file and logs, whether the gateway answers
magpie daemon restart    # after updating magpie
magpie daemon stop|start
magpie daemon uninstall  # stop it and remove the file
magpie daemon web on     # the service serves the browser page too; off stops it, no word shows it
```

--------------------------------

### magpie plugin add ./alias.middleware.js

Source: https://github.com/yetone/magpie/blob/main/site/public/docs/plugins.html

Command to install the example middleware from a local file or a package with a 'magpie' middleware field in its package.json.

```shell
magpie plugin add ./alias.middleware.js   # or a package whose package.json has "magpie": { "middleware": "./mw.js" }
```

--------------------------------

### Install Magpie from source with Go

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Installs the latest Magpie version directly from source using the Go toolchain.

```sh
go install github.com/yetone/magpie@latest
```

--------------------------------

### Install opencode-claude-auth plugin via LLM prompt

Source: https://github.com/yetone/magpie/blob/main/internal/plugin/testdata/github/raw/griffinmartin/opencode-claude-auth/HEAD/README.md

Prompt to give to an LLM agent to install and configure the plugin automatically. The agent should follow the linked installation instructions.

```text
Install the opencode-claude-auth plugin and configure it by following: https://raw.githubusercontent.com/griffinmartin/opencode-claude-auth/main/installation.md
```

--------------------------------

### Install magpie via curl

Source: https://github.com/yetone/magpie/blob/main/README.md

Downloads and runs the magpie installer script. Mac builds are signed and notarised, and every build updates itself. Behind a firewall, use --proxy or --mirror.

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

--------------------------------

### Install with proxy and set update mirror

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Shows how to pass a proxy to the installer and how to set a GitHub download mirror for `magpie update`. The proxy accepts http, https, socks5, or socks5h; the mirror is a prefix placed before the release's GitHub URL. No mirror is used unless given, and SHA-256 checks still come from usemagpie.ai.

```sh
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890
```

```sh
magpie update --mirror https://mirror.example/
```

--------------------------------

### Docker commands for setup, health, terminal, updates, and build

Source: https://github.com/yetone/magpie/blob/main/site/public/docs/docker.html

A collection of shell commands for managing the magpie container: setting ownership, starting with Compose, checking health, opening a terminal, pulling updates, and building the image from source.

```bash
sudo chown -R 65532:65532 ./config
```

```bash
docker compose up -d
```

```bash
docker exec -it magpie bash
```

```bash
docker pull ghcr.io/yetone/magpie:latest
```

```bash
docker rm -f magpie
```

```bash
docker compose pull && docker compose up -d
```

```bash
docker build -t magpie .
```

--------------------------------

### Install the agent plugin with magpie plugin add

Source: https://github.com/yetone/magpie/blob/main/site/public/docs/plugins.html

Shell command to add the agent plugin from a directory or a single *.agent.js file.

```shell
magpie plugin add ./agent-aider   # or a single *.agent.js file
```

--------------------------------

### GET /api/hello

Source: https://github.com/yetone/magpie/blob/main/docs/integrating.md

Health check endpoint to verify the gateway is magpie and get its version.

```APIDOC
## GET /api/hello

### Description
Returns a JSON object with the name and version of the gateway, confirming it is magpie.

### Method
GET

### Endpoint
/api/hello

### Response
#### Success Response (200)
- **name** (string) - Always "magpie".
- **version** (string) - The version of magpie.

#### Response Example
{
  "name": "magpie",
  "version": "..."
}
```

--------------------------------

### JavaScript: build import link with URLSearchParams

Source: https://github.com/yetone/magpie/blob/main/site/public/docs/import.html

Build an import link from your backend using URLSearchParams. The example sets name, chat, anthropic, key, models (comma-separated), and icon. Use this where you have a freshly minted API key.

```javascript
const params = new URLSearchParams({
  name: "Acme Relay",
  chat: "https://api.acme.example/v1",
  anthropic: "https://api.acme.example",
  key: apiKey,
  models: ["gpt-5.5", "claude-sonnet-5"].join(","),
  icon: "https://acme.example/logo.svg",
});
const href = "https://usemagpie.ai/import#" + params;
```

--------------------------------

### magpie plugin use command to switch provider to a specific plugin

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Shows how to make a specific plugin serve a provider id. The example uses a local plugin path and the provider id 'acme'.

```sh
magpie plugin use ~/dev/my-acme-auth acme   # this plugin serves acme from now on
```

--------------------------------

### magpie:// import link with preset

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Example import link using the preset parameter to specify a provider preset (e.g., deepseek) and an API key. Opening it in magpie shows the provider details; nothing is saved until the user presses Add. The magpie import <link> command does the same in a terminal.

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

--------------------------------

### magpie CLI usage examples

Source: https://github.com/yetone/magpie/blob/main/site/public/index.html

Shows common magpie CLI commands: adding providers, assigning models to agents, creating model groups, listing agents, saving/using profiles, and launching the TUI. Presets like `deepseek` need only a key; local servers like `ollama` need none.

```bash
# add providers
magpie provider add deepseek sk-…      # a preset needs only the key
magpie provider add moonshot sk-…
magpie provider add ollama             # local servers need none

# give agents third-party models
magpie codex deepseek/deepseek-v4-pro
magpie claude moonshot/kimi-k3
magpie gemini zhipu/glm-5.3
magpie opencode claude/claude-sonnet-5 # your Claude plan, in OpenCode

# one model over several providers
magpie group add opus models=claude/claude-opus-5-5,copilot/claude-opus-5.5 routing=order
magpie claude group/opus

magpie ls                              # every agent and its model
magpie save work && magpie use work    # profiles
magpie tui                             # the whole app, in the terminal
```

--------------------------------

### Run plugin-git test with node --test

Source: https://github.com/yetone/magpie/blob/main/internal/gui/tests/README.md

Command to run the plugin-git browser regression test with a concurrency of 1. This test verifies installing a plugin from a git repository, including the market field accepting a GitHub repo, the Install sending 'github:owner/repo', and the Installed tab showing the package name and README.

```sh
node --test --test-concurrency=1 internal/gui/tests/plugin-git.test.cjs
```

--------------------------------

### Install Claude Code in the container

Source: https://github.com/yetone/magpie/blob/main/site/public/docs/docker.html

Use this command to have Magpie download Anthropic's Claude Code build. It verifies the SHA-256 against Anthropic's manifest and stores it in /config/cache. Run again to get a newer version.

```shell
docker exec -it magpie magpie claude-code install
```

--------------------------------

### Install Magpie with proxy

Source: https://github.com/yetone/magpie/blob/main/site/public/docs/start.html

Use this command to install Magpie behind a firewall or without GitHub access. The --proxy flag accepts http, https, socks5, and socks5h protocols; HTTPS_PROXY and ALL_PROXY environment variables are also honored.

```bash
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890
```

--------------------------------

### Gateway middleware example

Source: https://github.com/yetone/magpie/blob/main/README.md

Example of a gateway middleware plugin that rewrites requests. The onRequest hook can modify or reject requests; onEvent and onResponse handle streamed events and full replies. Throwing or running too long leaves the request unchanged.

```js
// alias.middleware.js — magpie plugin add ./alias.middleware.js
export function onRequest(body, ctx) {
  if (body.model === "fast") return { ...body, model: "deepseek/deepseek-chat" };
}
```

--------------------------------

### Python: build import link with urlencode

Source: https://github.com/yetone/magpie/blob/main/site/public/docs/import.html

Build an import link from your backend using urllib.parse.urlencode. The example sets name, chat, anthropic, key, models (comma-separated), and icon. Use this where you have a freshly minted API key.

```python
from urllib.parse import urlencode

href = "https://usemagpie.ai/import#" + urlencode({
    "name": "Acme Relay",
    "chat": "https://api.acme.example/v1",
    "anthropic": "https://api.acme.example",
    "key": api_key,
    "models": "gpt-5.5,claude-sonnet-5",
    "icon": "https://acme.example/logo.svg",
})
```

--------------------------------

### alias.middleware.js - example middleware

Source: https://github.com/yetone/magpie/blob/main/site/public/docs/plugins.html

Example middleware that renames a model and can reject requests. It uses the 'message_start' event, modifies the request body in onRequest, and restores the original model name in onEvent.

```javascript
// alias.middleware.js
export const events = ["message_start"]

export function onRequest(body, ctx) {
  ctx.state.asked = body.model
  if (body.model === "fast") body.model = "deepseek/deepseek-chat"
  if ((ctx.options.blocked ?? []).includes(body.model)) return ctx.reject(403, "not this model")
  return body
}

export function onEvent(ev, ctx) {
  ev.message.model = ctx.state.asked  // the agent sees the name it asked for
  return ev
}
```

--------------------------------

### magpie:// import link with custom provider details

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Example import link specifying a custom provider name, chat and Anthropic base URLs, API key, and models. Opening it in magpie shows the provider details; nothing is saved until the user presses Add. The magpie import <link> command does the same in a terminal.

```text
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
```

--------------------------------

### magpie model wire examples

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Shows how to set a vendor-facing name for a model, use wildcards for all models, reset to the model's own name, and list current wire names. Quote arguments with `*` to avoid zsh globbing. `--reset` only removes the given name, and the CLI reports which name is in force after each change.

```sh
magpie model wire relay-b/model-2                           # what the vendor is asked for
magpie model wire relay-b/model-2 vendor-c/model-2-preview  # ask for it by this
magpie model wire 'relay-b/*' 'vendor-c/*'                  # every model, * being the model
magpie model wire relay-b/model-2 --reset                   # ask for it by its own name again
magpie model wires                                          # every name your vendors are asked for models by
```

--------------------------------

### GET /v1beta/models

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Retrieves the model catalog (Gemini-compatible version).

```APIDOC
## [GET] /v1beta/models

### Description
Retrieves the model catalog (Gemini-compatible version).

### Method
GET

### Endpoint
/v1beta/models

### Parameters
No parameters.

### Response
#### Success Response (200)
- **models** (array) - List of model objects.
  - **name** (string) - The model name.
  - **supportedGenerationMethods** (array) - List of supported generation methods.

#### Response Example
{
  "models": [
    {
      "name": "models/openai/gpt-4o",
      "supportedGenerationMethods": ["generateContent", "streamGenerateContent", "countTokens"]
    }
  ]
}
```

--------------------------------

### GET /v1/models

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Retrieves the model catalog. Each entry includes reasoning and supported_reasoning_levels fields.

```APIDOC
## [GET] /v1/models

### Description
Retrieves the model catalog. Each entry includes reasoning and supported_reasoning_levels fields.

### Method
GET

### Endpoint
/v1/models

### Parameters
No parameters.

### Response
#### Success Response (200)
- **data** (array) - List of model objects.
  - **id** (string) - The model identifier.
  - **reasoning** (boolean) - Whether the model supports reasoning.
  - **supported_reasoning_levels** (array) - List of supported reasoning levels, e.g., [{"effort":"low"}].
  - **native_endpoints** (array) - List of API endpoints the model is passed straight through on, e.g., ["/v1/messages"].

#### Response Example
{
  "data": [
    {
      "id": "openai/gpt-4o",
      "reasoning": true,
      "supported_reasoning_levels": [{"effort": "low"}, {"effort": "medium"}],
      "native_endpoints": ["/v1/messages"]
    }
  ]
}
```

--------------------------------

### GET /v1/models

Source: https://github.com/yetone/magpie/blob/main/docs/integrating.md

Lists the models available in the gateway, including metadata like context window and reasoning support.

```APIDOC
## GET /v1/models

### Description
Lists the models available in the gateway, including metadata like context window and reasoning support.

### Method
GET

### Endpoint
/v1/models

### Parameters
#### Query Parameters
- **format** (string) - Optional - If set to "text", returns only the model IDs, one per line.

### Response
#### Success Response (200)
- **id** (string) - The model ID (provider/model or routing group name).
- **display_name** (string) - The display name.
- **owned_by** (string) - The provider.
- **reasoning** (boolean) - Whether reasoning is supported.
- **supported_reasoning_levels** (array) - Supported reasoning levels, e.g., [{"effort":"low"}].
- **context_window** (integer) - The context window size, if known.
- **max_output_tokens** (integer) - The maximum output tokens, if known.
- **modalities** (array) - Supported modalities, e.g., ["image"], if known.

#### Response Example
{
  "id": "provider/model",
  "display_name": "Model Name",
  "owned_by": "provider",
  "reasoning": true,
  "supported_reasoning_levels": [
    {
      "effort": "low"
    }
  ],
  "context_window": 128000,
  "max_output_tokens": 4096,
  "modalities": [
    "image"
  ]
}
```

--------------------------------

### Run magpie container with web UI and gateway key

Source: https://github.com/yetone/magpie/blob/main/site/public/docs/docker.html

Starts a magpie container with the browser UI on port 3430 and the gateway on 3425, using a random web key and a named volume for config. The log output shows the web page URL with the key and warns about unencrypted network access.

```shell
docker run -d --name magpie --restart unless-stopped \
  -p 127.0.0.1:3425:3425 -p 127.0.0.1:3430:3430 \
  -e MAGPIE_WEB_KEY=$(openssl rand -hex 16) \
  -v magpie-config:/config \
  ghcr.io/yetone/magpie:latest web --addr 0.0.0.0:3430 --no-open

docker logs magpie
```

```output
● magpie web on http://127.0.0.1:3430/?k=0f3c9a1e…
  on the network http://172.17.0.2:3430/?k=0f3c9a1e…
  these are the container's own addresses: other machines use the host's, and MAGPIE_PUBLIC_URL=http://<host>:<port> puts it here
! anyone with the link can change magpie and see its keys, and the network carries it unencrypted
  the link carries MAGPIE_WEB_KEY · gateway http://127.0.0.1:3425 · Ctrl-C to stop
```

--------------------------------

### Serve HTTPS with TLS certificates

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Use this command to run magpie with HTTPS using Let's Encrypt certificates. The certificate and key files must be PEM format. If one is missing or fails to load, magpie refuses to start. The certificate is reloaded on file changes, so renewals are picked up without restart.

```sh
magpie serve --tls-cert /etc/letsencrypt/live/relay.example.com/fullchain.pem \
             --tls-key  /etc/letsencrypt/live/relay.example.com/privkey.pem
```

--------------------------------

### GET /api/sessions/overview

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/gateway-sessions.md

Returns top summaries with model_effort added to tokens, cost, and active summaries. Supports days parameter to control history range.

```APIDOC
## GET /api/sessions/overview

### Description
Returns top summaries with model_effort added to tokens, cost, and active summaries. Supports days parameter to control history range.

### Method
GET

### Endpoint
/api/sessions/overview

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Number of days to include in the summary. Use 0 for all history.

### Response
#### Success Response (200)
- **tokens** (object) - Token summary including model_effort.
- **cost** (object) - Cost summary including model_effort.
- **active** (object) - Active summary including model_effort.
- **models** (array) - Existing models field, unchanged.

#### Response Example
{
  "tokens": {
    "model_effort": {}
  },
  "cost": {
    "model_effort": {}
  },
  "active": {
    "model_effort": {}
  },
  "models": []
}
```

--------------------------------

### Go test: settings TestRanBefore

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/plugin-runtime.md

Runs the settings test TestRanBefore.

```bash
go test ./internal/settings/ -run TestRanBefore
```

--------------------------------

### settings.json with privacy switches

Source: https://github.com/yetone/magpie/blob/main/site/public/docs/privacy.html

Example settings.json that disables all usage statistics and automatic updates. Place this file in magpie's folder. Changes take effect at the next hourly look; no restart is needed.

```json
{
  "noStats": true,
  "noUsageStats": true,
  "noAutoUpdate": true
}
```

--------------------------------

### Run font tests with node and go

Source: https://github.com/yetone/magpie/blob/main/internal/gui/tests/README.md

Commands to run the font-related tests. The node command runs three test files, the go test commands run font and settings tests. The native test reads actual installed font metadata; run without nogui on each desktop platform.

```sh
node --test internal/gui/tests/fonts.test.cjs internal/gui/tests/font-cascade.test.cjs internal/gui/tests/win-fonts.test.cjs
go test -v ./internal/fonts
go test -tags nogui ./internal/settings ./internal/gui -run '^TestFont'
```

--------------------------------

### Add plugins via CLI

Source: https://github.com/yetone/magpie/blob/main/README.md

Commands to add plugins from npm or pi packages, and to log in to a plugin. Plugins run on Bun and are downloaded on first use.

```sh
magpie plugin add opencode-gemini-auth   # an OpenCode plugin from npm
magpie plugin add pi-antigravity         # a pi package, the same way
magpie plugin login google-plugin        # its own sign-in flow, in magpie
```

--------------------------------

### Docker Compose for Magpie NAS gateway

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Example Docker Compose project for running Magpie as a gateway on a NAS. It binds the web UI to loopback and the gateway port to 127.0.0.1, requiring a gateway key for remote agents. Change the gateway mapping to 3425:3425 to let remote agents reach it.

```yaml
services:
  magpie:
    image: ghcr.io/yetone/magpie:latest
    restart: unless-stopped
    ports:
      # 127.0.0.1: the host alone; every caller outside the container needs a gateway key.
      - "127.0.0.1:3425:3425"
      - "127.0.0.1:3430:3430"
    environment:
      MAGPIE_ADDR: 0.0.0.0:3425
      MAGPIE_PUBLIC_URL: http://<nas-address>:3425
      MAGPIE_WEB_KEY: <random-key>
    volumes:
      - ./config:/config
    command: [web, --addr, 0.0.0.0:3430, --no-open]
```

--------------------------------

### Magpie provider management CLI commands

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Commands to list, add, inspect, modify, test, and remove providers, and to manage exposed models. Includes presets, custom relays, model selection, refresh intervals, auto-include patterns, and usage examples.

```sh
magpie presets                          # the vendors magpie knows, grouped: vendors, relays, local
magpie provider add deepseek sk-…       # a preset needs only the key
magpie provider add ollama              # local servers need none
magpie provider add "My Relay" url=https://relay.example.com/v1 key=sk-… models=gpt-5.5,claude-sonnet-5
magpie providers                        # host, key, exposed models, who uses what
magpie provider deepseek                # one provider in detail
magpie provider models deepseek         # re-fetch the vendor's list (add ids to choose which to expose)
magpie provider models deepseek +deepseek-v4 -deepseek-chat   # expose one more, take one out; the rest stay
magpie provider models deepseek a b c   # the whole list of models to expose, replacing it (all: the default)
magpie provider refresh deepseek        # re-fetch it, and drop picks it no longer has (the TUI: m)
magpie provider refresh-every relay 6h  # the gateway fetches its list every 6h (1d, 30m; off; at least 10m)
magpie provider auto-include relay 'gpt-*' 're:claude-.*'  # a newly listed model these match is exposed (none clears)
magpie provider test deepseek           # one tiny request per API, with latency
magpie provider key deepseek sk-…       # replace the key
magpie provider rm deepseek
magpie models                           # the catalog agents see
magpie claude deepseek/deepseek-chat    # use it
```

--------------------------------

### Set Zed-compatible agent environment variables and start Magpie

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Configure Magpie to use a Zed-compatible fork by setting MAGPIE_ZED_BIN, MAGPIE_ZED_CONFIG_DIR, and MAGPIE_ZED_PROCESS_NAMES before running magpie serve. These variables affect the Magpie process in which they are set; put them in the service environment when running under systemd or Docker.

```sh
export MAGPIE_ZED_BIN=/Applications/ZedG.app/Contents/MacOS/zedg
export MAGPIE_ZED_CONFIG_DIR="$HOME/.config/zed"
export MAGPIE_ZED_PROCESS_NAMES=zedg,ZedG
magpie serve
```

--------------------------------

### Run update-mirror.test.cjs

Source: https://github.com/yetone/magpie/blob/main/internal/gui/tests/README.md

Executes the test file for update mirror settings and download source behavior.

```sh
node --test internal/gui/tests/update-mirror.test.cjs
```

--------------------------------

### Run build and test suite commands

Source: https://github.com/yetone/magpie/blob/main/docs/code-standards.md

Commands to run for the build and suite acceptance criterion. Includes formatting check, vet, cross-OS builds, and tests. Use `set -o pipefail` in a chain to stop on failure. Run `./...` to include guard tests.

```bash
gofmt -l
```

```bash
go vet ./...
```

```bash
GOOS=linux go vet -tags nogui ./...
```

```bash
GOOS=windows go vet ./...
```

```bash
go build
```

```bash
GOOS=linux go build -tags nogui
```

```bash
GOOS=windows go build
```

```bash
go test -tags nogui ./...
```

```bash
set -o pipefail
```

```bash
go test | tail && git push
```

--------------------------------

### OpenCode plugin example with magpie-specific fields

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Example of an OpenCode plugin's auth hook that includes magpie-specific fields: 'icon' for the provider icon and a 'label' and 'placeholder' for an API key method. The comment shows the icon can be a data URI.

```js
export const LemonPlugin = async () => ({
  auth: {
    provider: "lemon",
    icon: "https://lemon.example/icon.png", // or "data:image/svg+xml;base64,…"
    methods: [
      { type: "api", label: "Lemon API key (lemon.example/keys)", placeholder: "sk-lemon-…" },
    ],
  },
})
```

--------------------------------

### GET /v1/magpie/limit

Source: https://github.com/yetone/magpie/blob/main/docs/integrating.md

Returns the key's own limit.

```APIDOC
## GET /v1/magpie/limit

### Description
Returns the key's own limit.

### Method
GET

### Endpoint
/v1/magpie/limit

### Response
#### Success Response (200)
- **limit** (object) - The limit details.

#### Response Example
{
  "limit": {
    "max_requests": 1000,
    "used": 100
  }
}
```

--------------------------------

### Run all verification tests

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/sync-backup.md

Runs the Go tests for the davsync and cli packages, and the Node.js tests for GUI sync. The Go tests use testenv homes and HTTP fixtures; browser tests use isolated API fixtures in Chromium and WebKit. A live GitHub write requires a test repository and token.

```sh
go test -tags nogui ./internal/davsync
go test -tags nogui ./internal/cli -run 'TestGitHubCmd|TestWebdavCmd|TestS3Cmd'
node --test internal/gui/tests/github-sync.test.cjs internal/gui/tests/s3-sync.test.cjs internal/gui/tests/sync-other-kind.test.cjs
```

--------------------------------

### GET /v1/magpie/usage

Source: https://github.com/yetone/magpie/blob/main/docs/integrating.md

Returns the Usage page's numbers.

```APIDOC
## GET /v1/magpie/usage

### Description
Returns the Usage page's numbers.

### Method
GET

### Endpoint
/v1/magpie/usage

### Response
#### Success Response (200)
- **usage** (object) - The usage statistics.

#### Response Example
{
  "usage": {
    "total_tokens": 1000,
    "requests": 10
  }
}
```

--------------------------------

### Add a subscription account via Docker exec

Source: https://github.com/yetone/magpie/blob/main/site/public/docs/docker.html

Run this command inside the Magpie container to add a subscription account (e.g., Codex). It prints a link to open, then you paste the callback URL after signing in.

```shell
docker exec -it magpie magpie accounts add codex
```

--------------------------------

### GET /v1/magpie/quotas

Source: https://github.com/yetone/magpie/blob/main/docs/integrating.md

Lists the user's subscription allowances.

```APIDOC
## GET /v1/magpie/quotas

### Description
Lists the user's subscription allowances.

### Method
GET

### Endpoint
/v1/magpie/quotas

### Response
#### Success Response (200)
- **quotas** (array) - The subscription allowances.

#### Response Example
{
  "quotas": [
    {
      "provider": "provider",
      "limit": 1000,
      "used": 100
    }
  ]
}
```

--------------------------------

### GET /v1/codex/models

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Retrieves the model catalog as Codex's model_catalog_url reads it.

```APIDOC
## [GET] /v1/codex/models

### Description
Retrieves the model catalog as Codex's model_catalog_url reads it.

### Method
GET

### Endpoint
/v1/codex/models

### Parameters
No parameters.

### Response
#### Success Response (200)
- **data** (array) - List of model objects in Codex format.

#### Response Example
{
  "data": [
    {
      "id": "openai/gpt-4o",
      "reasoning": true
    }
  ]
}
```

--------------------------------

### Go test: routes and rotation plugin tests

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/plugin-runtime.md

Runs routes and rotation plugin tests, including TestRegisterStacks, TestApplyFailsOpen, the strategies' orders, TestOnServesOffDoesNot, and TestInUse.

```bash
go test ./internal/routes/ ./plugins/rotation/
```

--------------------------------

### GET /api/sessions/manage

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/gateway-sessions.md

Returns session management data with model_effort for each Codex thread.

```APIDOC
## GET /api/sessions/manage

### Description
Returns session management data with model_effort for each Codex thread.

### Method
GET

### Endpoint
/api/sessions/manage

### Response
#### Success Response (200)
- **model_effort** (object) - Grouped by model and effective reasoning effort, containing token usage and cost.

#### Response Example
{
  "model_effort": {
    "model": "gpt-5",
    "effort": "high",
    "input_tokens": 100,
    "output_tokens": 50,
    "cached_tokens": 10,
    "cache_write_tokens": 5,
    "reasoning_tokens": 20,
    "cost": 0.01,
    "priced": true
  }
}
```

--------------------------------

### Go test: OTLP and otel plugin tests

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/plugin-runtime.md

Runs OTLP and otel plugin tests, including TestOnExportsOffSendsNothing and TestInUseByEnvironment.

```bash
go test ./internal/otlp/ ./plugins/otel/
```

--------------------------------

### GET /v1/magpie/usage

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Returns usage information. Restricted for gateway keys with limited access.

```APIDOC
## GET /v1/magpie/usage

### Description
Returns usage information. Restricted for gateway keys with limited access.

### Method
GET

### Endpoint
/v1/magpie/usage

### Response
#### Success Response (200)
- **usage** (object) - Usage details.

#### Error Response (403)
- **code** (string) - Error code, e.g., `gateway_key_held`.

#### Response Example
{
  "usage": {}
}
```

--------------------------------

### GET /v1/magpie/concurrency

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Returns concurrency information. Restricted for gateway keys with limited access.

```APIDOC
## GET /v1/magpie/concurrency

### Description
Returns concurrency information. Restricted for gateway keys with limited access.

### Method
GET

### Endpoint
/v1/magpie/concurrency

### Response
#### Success Response (200)
- **concurrency** (integer) - Current concurrency limit.

#### Error Response (403)
- **code** (string) - Error code, e.g., `gateway_key_held`.

#### Response Example
{
  "concurrency": 10
}
```

--------------------------------

### Run GUI verification tests

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/gui-shell.md

Commands to run the Go tests for the GUI package and the Playwright-based UI tests. The first two commands run the GUI tests; the third is for Intel Mac builds; the fourth is for Windows WebView2 tests; the fifth runs font discovery tests; the last two run the UI test suite. Note that `make test-ui` requires Node.js and Playwright, and the CI Test workflow does not run this suite.

```sh
go test -tags nogui ./internal/gui
go test -run TestMainWindow ./internal/gui
GOARCH=amd64 CGO_ENABLED=1 go test -run TestMainWindow ./internal/gui  # as for an Intel Mac
go test -run TestWebView2 ./internal/gui   # on Windows: Wails' runtime lookup, missing and present
go test -v ./internal/fonts         # native discovery on each desktop OS
make test-ui                      # every internal/gui/tests/*.test.cjs, Chromium and WebKit
BROWSER=webkit node --test internal/gui/tests/click-scroll.test.cjs
```

--------------------------------

### Build Magpie locally with Make targets

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Lists the available Make targets for building Magpie locally. `make build` produces the desktop app (requires cgo and the platform webview), `make app` creates a macOS menu bar app, `make cli` builds a terminal-only version, and the release targets build distributable artifacts for each platform.

```sh
make build            # ./magpie with the desktop app (needs cgo + the platform webview)
```

```sh
make app              # macOS: magpie.app, a menu bar app with no Dock icon
```

```sh
make cli              # terminal-only build, no cgo, cross-compiles anywhere
```

```sh
make release          # dist/: native app build + cli builds for every platform
```

```sh
make release-windows  # dist/: the Windows app, amd64 and arm64 (cross-compiles)
```

```sh
make release-linux    # dist/: the Linux app for this machine's arch
```

--------------------------------

### GET /api/sessions/one

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/gateway-sessions.md

Returns a single session with model_effort for the Codex thread, similar to /api/sessions.

```APIDOC
## GET /api/sessions/one

### Description
Returns a single session with model_effort for the Codex thread, similar to /api/sessions.

### Method
GET

### Endpoint
/api/sessions/one

### Response
#### Success Response (200)
- **model_effort** (object) - Grouped by model and effective reasoning effort, containing token usage and cost.

#### Response Example
{
  "model_effort": {
    "model": "gpt-5",
    "effort": "high",
    "input_tokens": 100,
    "output_tokens": 50,
    "cached_tokens": 10,
    "cache_write_tokens": 5,
    "reasoning_tokens": 20,
    "cost": 0.01,
    "priced": true
  }
}
```

--------------------------------

### Run Tencent Access Key and Provider List Tests

Source: https://github.com/yetone/magpie/blob/main/internal/gui/tests/README.md

Commands to run the Tencent access key test and the provider list test. The first runs the Node test file, the second runs the Go test with the nogui tag.

```sh
node --test internal/gui/tests/tencent-access-key.test.cjs
go test -tags nogui ./internal/gui -run TestProviderListTellsTencentAccessKey
```

--------------------------------

### GET /v1/magpie/usage/requests

Source: https://github.com/yetone/magpie/blob/main/docs/integrating.md

Returns the Usage page's requests, including session and subagent/parent_agent information.

```APIDOC
## GET /v1/magpie/usage/requests

### Description
Returns the Usage page's requests, including session and subagent/parent_agent information.

### Method
GET

### Endpoint
/v1/magpie/usage/requests

### Response
#### Success Response (200)
- **requests** (array) - The list of requests.

#### Response Example
{
  "requests": [
    {
      "session": "session-id",
      "subagent": "subagent-id",
      "parent_agent": "parent-agent-id"
    }
  ]
}
```

--------------------------------

### Go test: gateway whole

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/plugin-runtime.md

Runs the entire gateway test suite. Its TestMain registers the strategies, so every routing test is the parity run with the plugin on; TestRotationOnAndOff turns it off.

```bash
go test ./internal/gateway/
```

--------------------------------

### GET /v1/magpie/route

Source: https://github.com/yetone/magpie/blob/main/site/public/docs/integrate.html

Returns which model a routing group picked for a turn and the fallbacks tried, before the first token.

```APIDOC
## GET /v1/magpie/route

### Description
Given a session ID, returns the model selected by a routing group for the current turn and the fallbacks that were attempted. Supports long-polling with `after` and `wait` parameters.

### Method
GET

### Endpoint
/v1/magpie/route

### Parameters
#### Query Parameters
- **session** (string) - Required - The session ID of the conversation.
- **after** (integer) - Optional - Sequence number for long-polling.
- **wait** (integer) - Optional - Wait time in seconds for long-polling.

### Response
#### Success Response (200)
- **model** (string) - The model selected by the routing group.
- **fallbacks** (array) - List of fallback models tried.

#### Response Example
{
  "model": "routing-group/model",
  "fallbacks": ["provider1/model1", "provider2/model2"]
}
```

--------------------------------

### Run all Go library tests

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/library.md

Runs the full test suite for the internal/library package with the 'nogui' build tag. This covers all library functionality without GUI dependencies.

```sh
go test -tags nogui ./internal/library
```

--------------------------------

### GET /v1/models

Source: https://github.com/yetone/magpie/blob/main/site/public/docs/integrate.html

Lists the models the user has enabled in magpie, including provider, display name, and capabilities.

```APIDOC
## GET /v1/models

### Description
Returns a list of models available through the gateway. The list is dynamic based on the user's enabled providers and routing groups.

### Method
GET

### Endpoint
/v1/models

### Parameters
#### Query Parameters
- **format** (string) - Optional - If set to "text", returns only the model IDs, one per line.

### Request Example
curl -s http://127.0.0.1:3425/v1/models -H "Authorization: Bearer magpie-acme"

### Response
#### Success Response (200)
- **id** (string) - The model identifier, typically "provider/model" or a routing group name.
- **display_name** (string) - The display name of the model.
- **owned_by** (string) - The provider that owns the model.
- **reasoning** (boolean) - Whether the model supports reasoning.
- **supported_reasoning_levels** (array) - List of supported reasoning effort levels, e.g., [{"effort":"low"}].
- **context_window** (integer) - The context window size, if known.
- **max_output_tokens** (integer) - The maximum output tokens, if known.
- **modalities** (array) - The modalities supported (e.g., images), if known.

#### Response Example
{
  "id": "provider/model",
  "display_name": "Model Name",
  "owned_by": "provider",
  "reasoning": true,
  "supported_reasoning_levels": [{"effort":"low"}],
  "context_window": 128000,
  "max_output_tokens": 4096,
  "modalities": ["text", "image"]
}
```

--------------------------------

### GET /api/usage/requests

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/gateway-sessions.md

Returns usage request data including session_role and compaction fields for Codex calls.

```APIDOC
## GET /api/usage/requests

### Description
Returns usage request data including session_role and compaction fields for Codex calls.

### Method
GET

### Endpoint
/api/usage/requests

### Response
#### Success Response (200)
- **session_role** (string) - Classifies the canonical Codex actor as 'main', 'subagent', or 'unknown'.
- **session** (string) - Root thread ID for confirmed identity; empty if actor known but root not.
- **subagent** (string) - Child thread ID for Codex.
- **parent_agent** (string) - Parent thread ID when known and itself a subagent.
- **native_session** (string) - Recorded native header.
- **compaction** (boolean) - Present only when native Codex call establishes marker state; true or false.

#### Response Example
{
  "session_role": "main",
  "session": "thread_123",
  "subagent": "thread_456",
  "parent_agent": "thread_789",
  "native_session": "header_value",
  "compaction": true
}
```

--------------------------------

### Run the full UI test suite with make test-ui

Source: https://github.com/yetone/magpie/blob/main/internal/gui/tests/README.md

Runs every internal/gui/tests/*.test.cjs file automatically. Files run a few at a time (UI_TEST_CONCURRENCY, default 2); set UI_TEST_CONCURRENCY=1 to run one at a time when diagnosing a flaky file.

```sh
make test-ui
```

--------------------------------

### GET /v1/magpie/route

Source: https://github.com/yetone/magpie/blob/main/docs/integrating.md

Returns which model a routing group picked for a session and the fallbacks tried, before the first token.

```APIDOC
## GET /v1/magpie/route

### Description
Returns which model a routing group picked for a session and the fallbacks tried, before the first token.

### Method
GET

### Endpoint
/v1/magpie/route

### Parameters
#### Query Parameters
- **session** (string) - Required - The session ID.
- **after** (string) - Optional - Sequence number for long-polling.
- **wait** (integer) - Optional - Wait time in seconds for long-polling.

### Response
#### Success Response (200)
- **model** (string) - The selected model.
- **fallbacks** (array) - The fallback models tried.

#### Response Example
{
  "model": "provider/model",
  "fallbacks": [
    "provider/fallback1",
    "provider/fallback2"
  ]
}
```

--------------------------------

### Run Volcengine access key tests

Source: https://github.com/yetone/magpie/blob/main/internal/gui/tests/README.md

Commands to run the Volcengine access key test and the server-side test. The first runs the Node test file, the second runs the Go test with the nogui tag.

```sh
node --test internal/gui/tests/volc-access-key.test.cjs
go test -tags nogui ./internal/gui -run TestProviderSaveKeepsVolcengineSecret
```

--------------------------------

### GET /v1/magpie/quotas/history

Source: https://github.com/yetone/magpie/blob/main/docs/reference.md

Retrieves historical quota usage data. This endpoint is restricted for gateway keys with limited access.

```APIDOC
## GET /v1/magpie/quotas/history

### Description
Returns historical quota usage information. Restricted for gateway keys with limited access.

### Method
GET

### Endpoint
/v1/magpie/quotas/history

### Response
#### Success Response (200)
- **data** (array) - Historical quota usage records.

#### Error Response (403)
- **code** (string) - Error code, e.g., `gateway_key_held`.

#### Response Example
{
  "data": []
}
```

--------------------------------

### Go test: gateway observer tests

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/plugin-runtime.md

Runs gateway observer tests: TestObserverPoint, OTel, and Deferred.

```bash
go test ./internal/gateway/ -run 'TestObserverPoint|OTel|Deferred'
```

--------------------------------

### Run omp-profile-connect.test.cjs

Source: https://github.com/yetone/magpie/blob/main/internal/gui/tests/README.md

Executes the test file for OMP named profile connection switch behavior.

```sh
node --test internal/gui/tests/omp-profile-connect.test.cjs
```

--------------------------------

### Verification commands for middleware and plugins

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/gateway-middleware.md

Commands to run tests and benchmarks for the middleware, gateway, plugin list, plugin options, and GUI tests, as well as plugin package tests.

```sh
go test -tags nogui ./internal/middleware
go test -tags nogui -run TestMiddlewareThroughGateway ./internal/gateway
go test -tags nogui -run TestPluginListSaysMiddleware .
go test -tags nogui -run "TestSetOptionsShortName|TestBuiltinMarket" ./internal/plugin
go test -tags nogui -bench Event ./internal/middleware
node --test internal/gui/tests/plugin-middleware.test.cjs
# in magpie-community/plugins: each package runs its cases.json through the hooks
bun test packages/think-tags packages/model-map packages/param-override packages/system-prompt packages/word-guard
```

--------------------------------

### Run verification tests with Go

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/provider-plugins.md

Runs the verification test suite for the magpie project. It creates a temporary home directory, preserves the Go environment paths, and executes 'go test -tags nogui' on the internal/provider, internal/gateway, and internal/plugin packages. Some migration and gateway plugin tests require Bun on PATH and use local plugin fixtures; they skip when Bun is unavailable.

```sh
(
	verification_home=$(mktemp -d) || exit
	trap 'chmod -R u+w "$verification_home"; rm -rf "$verification_home"' EXIT
	verification_gopath=$(go env GOPATH) || exit
	verification_modcache=$(go env GOMODCACHE) || exit
	verification_buildcache=$(go env GOCACHE) || exit
	HOME="$verification_home" GOPATH="$verification_gopath" GOMODCACHE="$verification_modcache" GOCACHE="$verification_buildcache" \
		go test -tags nogui ./internal/provider ./internal/gateway ./internal/plugin
)
```

--------------------------------

### Go test: GUI builtin tests

Source: https://github.com/yetone/magpie/blob/main/docs/subsystems/plugin-runtime.md

Runs GUI tests matching TestBuiltin and TestBootSaysBuiltinsOff, including TestBuiltinConfig and TestBuiltinClientsLoaded.

```bash
go test ./internal/gui/ -run 'TestBuiltin|TestBootSaysBuiltinsOff'
```