Run magpie on a server

Install#

Deploy starts magpie, connects it to exe.dev's models, and checks that Claude Code answers through it. To do it yourself:

ssh exe.dev new --name=my-magpie
ssh my-magpie.exe.xyz

sudo systemctl enable --now docker.service
mkdir -p ~/magpie/config && cd ~/magpie
sudo chown 65532:65532 config
install -m 600 /dev/null .env
cat > .env <<EOF
MAGPIE_WEB_KEY=$(openssl rand -hex 16)
MAGPIE_PUBLIC_URL=https://$(hostname).exe.xyz:3425
EOF

cat > compose.yaml <<'EOF'
services:
  magpie:
    image: ghcr.io/yetone/magpie:stable
    restart: unless-stopped
    ports:
      - "127.0.0.1:3425:3425"   # the gateway
      - "127.0.0.1:3430:3430"   # the web UI
    env_file: .env
    volumes:
      - ./config:/config
    command: [web, --addr, 0.0.0.0:3430, --no-open]
EOF
docker compose up -d
sleep 10
docker compose ps

sudo tee /usr/local/bin/magpie >/dev/null <<'EOF'
#!/bin/sh
# magpie's CLI, run in its container
if [ -t 0 ]; then t=; else t=-T; fi
exec docker compose -f "$HOME/magpie/compose.yaml" exec $t magpie magpie "$@"
EOF
sudo chmod +x /usr/local/bin/magpie
magpie --version

magpie provider add exe-claude anthropic=https://llm.int.exe.xyz key=exe-gateway \
  models=claude-opus-5-5,claude-sonnet-5-5,claude-haiku-5-5
magpie provider add exe url=https://llm.int.exe.xyz/v1 key=exe-gateway \
  models=gpt-6-luna,fireworks/kimi-k3,fireworks/glm-5p3,fireworks/deepseek-v4p1-flash
magpie provider test exe-claude
magpie provider test exe

magpie group add "Open models" routing=order \
  models=exe/fireworks/kimi-k3,exe/fireworks/glm-5p3,exe/fireworks/deepseek-v4p1-flash

install -m 600 /dev/null ~/magpie/this-vm.key
magpie gateway-key add this-vm | grep -o 'sk-magpie-[A-Za-z0-9_-]*' > ~/magpie/this-vm.key
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3425/v1/models
curl -s http://127.0.0.1:3425/v1/models -H "Authorization: Bearer $(cat ~/magpie/this-vm.key)" | jq -r '.data[].id'

ANTHROPIC_BASE_URL=http://127.0.0.1:3425 ANTHROPIC_API_KEY=$(cat ~/magpie/this-vm.key) \
  claude -p --model group/open-models "Reply with exactly: OK"

Open the web UI#

magpie's web UI is where you add providers, make routing groups and keys, and watch every request. On your computer, print its address with its key:

ssh my-magpie.exe.xyz 'echo "https://$(hostname).exe.xyz:3430/?k=$(grep MAGPIE_WEB_KEY ~/magpie/.env | cut -d= -f2)"'

Open it and log in to exe.dev. magpie trades the key for a cookie that lasts 400 days, so later visits need only https://my-magpie.exe.xyz:3430/. Port 3430 is private: exe.dev's login decides who reaches it, and the web key keeps out anyone you've shared the VM with but not given the key. Anyone with both can see and change your providers and keys, so treat the link like a password.

The UI is in gateway mode: Providers, Routing, Gateway (its keys), Usage and Sessions. There's no Agents page, since the agents run on your other machines. Send a few requests through group/open-models and open Routing to see which member answered each one and why.

Use it from this VM#

Agents on the VM call http://127.0.0.1:3425 with the key in ~/magpie/this-vm.key. For Claude Code, add to ~/.bashrc:

export ANTHROPIC_BASE_URL=http://127.0.0.1:3425
export ANTHROPIC_API_KEY=$(cat ~/magpie/this-vm.key)

Then claude --model group/open-models, or any model magpie models lists, such as exe/fireworks/glm-5p3. Codex uses the OpenAI side, with Claude models too:

MAGPIE_API_KEY=$(cat ~/magpie/this-vm.key) codex exec --skip-git-repo-check \
  -m exe-claude/claude-haiku-5-5 -c model_provider=magpie \
  -c 'model_providers.magpie.name="magpie"' \
  -c 'model_providers.magpie.base_url="http://127.0.0.1:3425/v1"' \
  -c 'model_providers.magpie.env_key="MAGPIE_API_KEY"' \
  -c 'model_providers.magpie.wire_api="responses"' \
  "Reply with exactly: OK"

Anything else that takes a base URL works the same way: http://127.0.0.1:3425/v1 for an OpenAI client, http://127.0.0.1:3425 for an Anthropic or Gemini one, and a gateway key as its API key.

Use it from your laptop#

From outside exe.dev, a request needs two things: an exe.dev VM token, which gets it through the HTTPS proxy, and a magpie gateway key, which magpie checks. On your computer, make a token that only opens this VM (--exp sets when it stops working):

ssh exe.dev ssh-key generate-api-key --vm=my-magpie --label=magpie-laptop --exp=90d

Then make the laptop its own gateway key, so you can limit it and turn it off on its own. gateway-key list shows its ID:

ssh my-magpie.exe.xyz magpie gateway-key add laptop
ssh my-magpie.exe.xyz magpie gateway-key list

Optionally hold the key to a daily budget and some models (put its ID in place of KEY_ID):

ssh my-magpie.exe.xyz magpie gateway-key limit KEY_ID day --cost 5
ssh my-magpie.exe.xyz magpie gateway-key models KEY_ID "'exe/*'" group/open-models

A request for any other model then gets a 403 that names the models the key may use. The exe.dev token goes in the X-Exedev-Authorization header, which exe.dev checks and strips (HTTPS tokens for VMs). For Claude Code on your laptop:

export ANTHROPIC_BASE_URL=https://my-magpie.exe.xyz:3425
export ANTHROPIC_API_KEY=sk-magpie-key-paste-yours-here
export ANTHROPIC_CUSTOM_HEADERS="X-Exedev-Authorization: Bearer exe1.paste-yours-here"
claude --model group/open-models

For Codex, add a provider to ~/.codex/config.toml, then run MAGPIE_API_KEY=sk-magpie-key-paste-yours-here codex -c model_provider=magpie -m group/open-models:

[model_providers.magpie]
name = "magpie"
base_url = "https://my-magpie.exe.xyz:3425/v1"
env_key = "MAGPIE_API_KEY"
wire_api = "responses"
supports_websockets = false
http_headers = { "X-Exedev-Authorization" = "Bearer exe1.paste-yours-here" }

We ran both from another machine with these settings: each answered through group/open-models. With the token but no gateway key, magpie answers 401; with the key but no token, exe.dev sends a login redirect.

CI jobs work the same way, with the token and a gateway key in the CI's secrets. magpie can also hand out short-lived keys that expire by themselves (magpie gateway-key issue --ttl 1h --name ci), so a job never holds a long-lived one.

Use it from your other VMs#

Your other exe.dev VMs don't need the exe.dev token: a VM-to-VM integration adds one at the network edge, where the calling VM can't read it. On your computer, attach one to the VMs that should use magpie (here my-agent-vm):

ssh exe.dev integrations add http-proxy --name magpie \
  --target https://my-magpie.exe.xyz:3425/ --peer --attach vm:my-agent-vm

Make that VM a gateway key of its own, as for the laptop, then on it:

export ANTHROPIC_BASE_URL=https://magpie.int.exe.xyz
export ANTHROPIC_API_KEY=sk-magpie-key-paste-yours-here
claude --model group/open-models

magpie's Usage page counts each VM's requests under its key's name. We ran this from a second VM: Claude Code answered through group/open-models, and a request without a gateway key got a 401.

Add providers#

Add the providers you have API keys for in the web UI (Providers → Add provider, then a preset and a key), or with the magpie command on the VM:

magpie presets                       # every vendor magpie knows
magpie provider add deepseek sk-...  # a preset needs only the key
magpie group add "Daily" routing=order models=deepseek/deepseek-v4-pro,group/open-models

A group can hold other groups, so Daily uses your DeepSeek key first and falls back to exe.dev's models when DeepSeek fails or runs out. We checked failover with a provider that couldn't be reached: the request was answered by the next member, and magpie's usage log marked it as answered on a retry.

A key you add to magpie is stored on the VM, in ~/magpie/config. To keep it off the VM:

• Anthropic, OpenAI and Fireworks: put your key in exe.dev's LLM integration ("API Key" instead of "exe.dev LLM gateway"). magpie's exe and exe-claude providers then use your key, with nothing to change on the VM.

• Other vendors: put the key in an HTTP proxy integration and give magpie the integration's address with a placeholder key. For DeepSeek, on your computer:

  printf '%s' "$DEEPSEEK_API_KEY" | ssh exe.dev integrations add http-proxy \
    --name deepseek --target https://api.deepseek.com --bearer=- --attach vm:my-magpie
  

  Then on the VM, a custom provider that knows DeepSeek's models (catalog=deepseek) but sends nothing to api.deepseek.com itself:

  magpie provider add "DeepSeek" id=deepseek url=https://deepseek.int.exe.xyz/v1 \
    anthropic=https://deepseek.int.exe.xyz/anthropic key=not-a-secret catalog=deepseek
  

  Give every URL this way: a preset given only url= still sends its Anthropic and Responses requests to the vendor. We checked which addresses and headers magpie uses, but haven't run this with a real DeepSeek key.

Back up and restore#

Everything magpie keeps is in ~/magpie: providers and their keys, gateway keys, routing groups, usage, and the web key in .env. Archive it on the VM, and keep the archive private:

mkdir -p ~/backups
cd ~/magpie && docker compose stop
sudo tar -C ~ -czf ~/backups/magpie-$(date +%F).tar.gz magpie
sudo chown $USER: ~/backups/magpie-*.tar.gz && chmod 600 ~/backups/magpie-*.tar.gz
docker compose start

To restore one, replace 2026-11-13 with the archive's date:

cd ~/magpie && docker compose down
sudo rm -rf ~/magpie
sudo tar -C ~ -xzf ~/backups/magpie-2026-11-13.tar.gz
cd ~/magpie && docker compose up -d

Your providers, groups and gateway keys come back as they were, so clients keep working. For a copy of the whole VM, run ssh exe.dev cp my-magpie my-magpie-backup on your computer.

Update#

magpie in Docker is updated by pulling a new image; settings stay in ~/magpie/config:

cd ~/magpie && docker compose pull && docker compose up -d
magpie --version

The stable tag moves about once a week. For every release, change it to latest in compose.yaml; to stay on one version, use its number (ghcr.io/yetone/magpie:0.1.3078). See the releases.

Troubleshooting#

• 401 from the gateway. The request has no enabled gateway key, or sent it in the wrong place. Send it as Authorization: Bearer or x-api-key; the web UI's cookie and the web key aren't gateway keys.
• A login page or 307 instead of an answer. The request reached exe.dev's proxy without a VM token. Check the X-Exedev-Authorization: Bearer exe1... header, and that the token was made with --vm=my-magpie and hasn't expired.
• 403 for a model. That key is held to some models: magpie gateway-key list shows which, and magpie gateway-key models <id> all lifts it.
• The web UI says 401. Open it once with ?k= and the web key, as in "Open the web UI"; a new browser needs it again.
• It's gone after a reboot. systemctl is-enabled docker.service should say enabled; run sudo systemctl enable --now docker.service if not.
• permission denied under /config in the log. The folder isn't the container's: sudo chown -R 65532:65532 ~/magpie/config, then docker compose restart.
• A provider fails. magpie provider test <id> sends one small request per API and prints the vendor's error.

For everything else, see magpie's Docker guide and reference, or ask on its Discord.