Docs · Servers
+magpie in Docker
+Run magpie on a server or a NAS that has no desktop: its gateway serves your models to agents on other computers, and you add providers and sign in to subscriptions from a page in your browser.
+ +| Image | ghcr.io/yetone/magpie, for linux/amd64 and linux/arm64 |
| Tags | latest (the newest release), 0.1.1150 (one release), 0.1, edge (every change on main) |
| Ports | 3425 the gateway agents call; 3430 the browser UI, when the container runs magpie web |
| Volume | /config: providers, keys, sign-ins, plugins and usage |
| User | nonroot (uid 65532) |
The image holds magpie’s terminal-only build on distroless, with bash and busybox for a terminal in the container. It runs magpie serve (the gateway alone) unless given another command. The container finds no agents to wire, so magpie in it is a gateway: the agents that use it run elsewhere.
Run it
+Run it with the browser UI, a key for that page you keep across restarts, and both ports on the host’s loopback only:
+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+
The log names the page with its key:
+● 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+
Bearer magpie included). -p 3425:3425 would publish it on every interface of the host, past its firewall. Publish it further only after sharing is on and you have a gateway key.Without web --addr 0.0.0.0:3430 --no-open the container runs the gateway alone, which you then set up from a terminal in it (docker exec -it magpie magpie provider add …). A folder bind-mounted at /config works in place of the named volume, if uid 65532 can write it: sudo chown -R 65532:65532 /volume1/docker/magpie/config.
The browser UI
+Open the link from the log. The key in it is traded for a cookie and taken out of the address; a page opened without it is turned away (401). With MAGPIE_WEB_KEY set (16 or more letters, digits or - . _ ~; openssl rand -hex 16 makes one) the key stays the same across restarts and the browser stays signed in for 400 days. Without it, every start makes a new key and the cookie lasts the browser session.
The page is in gateway mode: Providers, Gateway, Routing, Usage, Plugins and Settings, with no Agents, Sessions or Library, since there are no agents in the container. Settings → General → Gateway mode turns it off.
+On a NAS or a server you reach over SSH, open the page through a tunnel rather than publishing 3430: ssh -L 3430:127.0.0.1:3430 you@nas, then the log’s link on your own computer.
Sign in to subscriptions
+Add API keys on Providers as on the desktop. A subscription’s sign-in (ChatGPT, Claude…) opens the vendor’s page in your browser, and when you are done the vendor sends that browser back to localhost, for ChatGPT http://localhost:1455/auth/callback?code=…. That is your own computer, not the container, so the page doesn’t load. Copy its whole address from the address bar and paste it into the sign-in’s Callback URL field.
The same from a terminal:
+docker exec -it magpie magpie accounts add codex+
Open the link it prints, sign in, then paste the address the browser ended on. The browser UI can also import sign-ins from a file.
+ +What is kept
+Everything magpie writes is under /config, so a restart, or a new container on the same volume, keeps your providers, keys, sign-ins and plugins.
| Path | Holds |
|---|---|
/config/magpie | magpie’s own files: settings.json, providers, gateway keys, routing groups |
/config/home | the container’s HOME: sign-ins kept where their agent keeps them (~/.codex, ~/.claude…) |
/config/cache | the model catalog, and Bun, which plugins run on (downloaded the first time one is used) |
/config/data, /config/state | the rest of what magpie keeps |
A volume made by an older image keeps working: magpie adds the folders it lacks when it starts. Only sign-ins made with that older image, which lived outside the volume, have to be made again.
+ +Environment
+| Variable | What it does |
|---|---|
MAGPIE_ADDR | where the gateway listens. The image sets 0.0.0.0:3425, so the published port reaches it. |
MAGPIE_PUBLIC_URL | the address other machines reach the gateway at, such as http://192.168.1.20:3425 (the host’s or the NAS’s, on the published port), or a reverse proxy’s base URL. In the container magpie sees only Docker’s own 172.17.x address; with this set, the address it shows and prints is the one to use. |
MAGPIE_WEB_KEY | the browser UI’s key, kept across restarts (16+ characters) |
HOME, XDG_CONFIG_HOME, XDG_CACHE_HOME, XDG_DATA_HOME, XDG_STATE_HOME | set by the image to the folders under /config above; leave them |
Share it with other machines
+-
+
- Turn on sharingIn the browser UI, Settings → Share on local network → On. That also makes a gateway key named Magpie. From then on every request from outside the container must carry an enabled gateway key, and one without gets 401. Without the UI, put
"lan": truein/config/magpie/settings.json.
+ - Give each client a keyGateway → Gateway keys, or in a terminal
docker exec magpie magpie gateway-key add "Laptop", which prints the newsk-magpie-key-…. A key can have its own daily, weekly or monthly limit and its own list of models (magpie gateway-key limit,magpie gateway-key models).
+ - Publish the portRecreate the container with
-p 3425:3425, or bound to the NAS’s LAN or VPN address (-p 192.168.1.20:3425:3425), and with-e MAGPIE_PUBLIC_URL=http://192.168.1.20:3425.
+
On each other computer, point the agent at the gateway with one of those keys as its API key: http://192.168.1.20:3425/v1 for an OpenAI client, http://192.168.1.20:3425 for an Anthropic or Gemini one. Model ids are provider/model, or a routing group’s; GET /v1/models lists them. If that computer runs magpie itself, add the container as a Remote magpie instead, and magpie wires its agents for you.
Docker Compose on a NAS
+services:
+ magpie:
+ image: ghcr.io/yetone/magpie:latest
+ restart: unless-stopped
+ ports:
+ # on loopback until sharing is on and there is a gateway key
+ - "127.0.0.1:3425:3425"
+ - "127.0.0.1:3430:3430"
+ environment:
+ 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]
+ Then: sudo chown -R 65532:65532 ./config, docker compose up -d, open http://127.0.0.1:3430/?k=<random-key> through an SSH tunnel, add your providers, turn on Share on local network and make a gateway key for each machine. Then change the gateway’s line to "3425:3425" (or the NAS’s LAN or VPN address) and run docker compose up -d again.
Health, terminal, updates
+-
+
- Health. The image has a
HEALTHCHECK:magpie healthcheckexits 0 while the gateway answers, underserveandwebalike, sodocker psshows the container as healthy and Compose can wait for it withdepends_on: condition: service_healthy.
+ - Terminal.
docker exec -it magpie bash, or a NAS panel’s terminal, opens a shell withmagpieon its PATH:magpie providers,magpie models,magpie usage,magpie quotaand the rest of the CLI.
+ - Updates. Pull the new image and recreate the container on the same volume:
docker pull ghcr.io/yetone/magpie:latest, thendocker rm -f magpieand the samedocker run, ordocker compose pull && docker compose up -d.
+ - Build it yourself.
docker build -t magpie .in a checkout of the repository makes the same image.
+
Questions or a setup worth sharing? Ask on Discord. The reference has the details.
+