From d86a4e0568d433bc3a031d484dfb31d93c38fe3b Mon Sep 17 00:00:00 2001 From: yetone Date: Sat, 10 Oct 2026 09:07:47 +0800 Subject: [PATCH] site: the docs have Docker and Remote magpie pages in English, Chinese and Japanese, listed in every docs page's contents and footer and linked from the READMEs (HuanCheng Bai on Discord) Until now, both were only in docs/reference.md. The new pages are at /docs/docker, /docs/remote and their zh/ and ja/ versions. - docker: the image, its tags, ports, the /config volume and the nonroot user. How to run it with the browser UI (`web --addr 0.0.0.0:3430 --no-open`, MAGPIE_WEB_KEY, the ?k= cookie). Signing in through the Callback URL paste or `docker exec ... magpie accounts add`. What /config keeps, the env vars, sharing with gateway keys, and a Compose file for a NAS. Healthcheck and updates. - remote: sharing the main magpie, then adding it as a Remote magpie from the app, the TUI (a/w/m) or `magpie provider add remote-magpie url=... id=office`. What comes over (models, groups, APIs, images, System One, embeddings, prices, quotas) and the errors magpie shows, quoted from remote_quotas.go and lan.go. The facts were checked against the code, not reference.md: - the Dockerfile ENV, VOLUME, HEALTHCHECK and EXPOSE; - docker.yml's tags; - web_cli.go; - the lanGuard in internal/gateway/lan.go; - the remote-magpie preset. The Docker page's warning says a Docker gateway answers anyone until sharing is on, because MAGPIE_ADDR is 0.0.0.0 there. The new links in the top nav bar carry a toc-only class: - docs.js still lists them in the contents; - the bar keeps today's width, since nine links overflowed it at 1024-1280px. `.steps li` gets min-width: 0, so a long inline code no longer widens the grid past a phone's width, where `overflow: hidden` clipped the text. Run: - Real containers from ghcr.io/yetone/magpie:latest (v0.1.1150): - the documented `docker run ... web` came up healthy, and its log output is what the page shows; - with "lan": true, `Bearer magpie` got 401 and a gateway key got 200; - a second container ran `provider add remote-magpie url=http://:3425 id=office` and listed office/test-relay/... models. - `node --test site/*.test.mjs`: 23 pass. - Playwright, in Chromium and WebKit, at 1280, 1024 and 390, light and dark: - no horizontal scroll and no nav overflow on all 20 docs pages; - every internal link and #anchor resolves. /zh/ and /ja/ are routed by the worker and return 200 live. --- README.md | 8 +- README.zh-CN.md | 8 +- site/public/docs.css | 4 +- site/public/docs/docker.html | 236 +++++++++++++++++++++++++++++ site/public/docs/import.html | 4 + site/public/docs/integrate.html | 4 + site/public/docs/intent.html | 4 + site/public/docs/ja/docker.html | 236 +++++++++++++++++++++++++++++ site/public/docs/ja/import.html | 4 + site/public/docs/ja/intent.html | 4 + site/public/docs/ja/plugins.html | 4 + site/public/docs/ja/remote.html | 183 ++++++++++++++++++++++ site/public/docs/ja/start.html | 4 + site/public/docs/plugins.html | 4 + site/public/docs/remote.html | 183 ++++++++++++++++++++++ site/public/docs/start.html | 4 + site/public/docs/zh/docker.html | 236 +++++++++++++++++++++++++++++ site/public/docs/zh/import.html | 4 + site/public/docs/zh/integrate.html | 4 + site/public/docs/zh/intent.html | 4 + site/public/docs/zh/plugins.html | 4 + site/public/docs/zh/remote.html | 183 ++++++++++++++++++++++ site/public/docs/zh/start.html | 4 + 23 files changed, 1326 insertions(+), 7 deletions(-) create mode 100644 site/public/docs/docker.html create mode 100644 site/public/docs/ja/docker.html create mode 100644 site/public/docs/ja/remote.html create mode 100644 site/public/docs/remote.html create mode 100644 site/public/docs/zh/docker.html create mode 100644 site/public/docs/zh/remote.html diff --git a/README.md b/README.md index f9e4e020..e0564de7 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ Runs on macOS, Windows and Linux (menu bar app, window, TUI, web UI and CLI), in curl -fsSL https://usemagpie.ai/install.sh | sh ``` -Mac builds are signed and notarised, and every build updates itself. Behind a firewall, use `--proxy` or `--mirror`. Or `go install github.com/yetone/magpie@latest`, or the [Docker image](docs/reference.md#docker). +Mac builds are signed and notarised, and every build updates itself. Behind a firewall, use `--proxy` or `--mirror`. Or `go install github.com/yetone/magpie@latest`, or the [Docker image](https://usemagpie.ai/docs/docker). **2 · Add a provider.** Open magpie and go to **Providers → Add provider**. Pick a preset and paste a key, or sign in with a subscription. @@ -251,8 +251,8 @@ Find them under Plugins › Discover › Gateway middleware. See [Gateway middle | | | | :-- | :-- | | **Local network** | Turn on *Share on local network* and give each client a named gateway key with its own daily, weekly or monthly token and cost limit | -| **Remote magpie** | A laptop uses the providers, accounts and groups of the magpie on your desktop, and still wires its own agents | -| **Docker** | Run `ghcr.io/yetone/magpie` on a server or a NAS and manage it from the web UI | +| **[Remote magpie](https://usemagpie.ai/docs/remote)** | A laptop uses the providers, accounts and groups of the magpie on your desktop, and still wires its own agents | +| **[Docker](https://usemagpie.ai/docs/docker)** | Run `ghcr.io/yetone/magpie` on a server or a NAS and manage it from the web UI | | **Sync** | Back up to a file, or sync machines over WebDAV (Nutstore, Nextcloud…) or S3 | ### Also @@ -272,6 +272,8 @@ Find them under Plugins › Discover › Gateway middleware. See [Gateway middle | **[Plugins](https://usemagpie.ai/docs/plugins)** | Use plugins and write your own | | **[Intent routing](https://usemagpie.ai/docs/intent)** | Route each turn by what it asks for | | **[Import links](https://usemagpie.ai/docs/import)** | "Add to magpie" buttons for provider websites | +| **[Remote magpie](https://usemagpie.ai/docs/remote)** | Use one magpie's providers and groups from your other computers | +| **[Docker](https://usemagpie.ai/docs/docker)** | Run magpie on a server or a NAS | ## Privacy diff --git a/README.zh-CN.md b/README.zh-CN.md index 5e058383..5330cf91 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -57,7 +57,7 @@ curl -fsSL https://usemagpie.ai/install.sh | sh ``` -Mac 版已签名并公证，每个版本都会自动更新。网络受限时可用 `--proxy` 或 `--mirror`。也可以 `go install github.com/yetone/magpie@latest`，或者用 [Docker 镜像](docs/reference.md#docker)。 +Mac 版已签名并公证，每个版本都会自动更新。网络受限时可用 `--proxy` 或 `--mirror`。也可以 `go install github.com/yetone/magpie@latest`，或者用 [Docker 镜像](https://usemagpie.ai/docs/zh/docker)。 **2 · 添加 provider。**打开 magpie，进入 **Providers → 添加 provider**。选一个预设、粘贴 key，或者登录一个订阅。 @@ -251,8 +251,8 @@ magpie plugin options model-map '{"mapping": {"fast": "deepseek/deepseek-chat"}} | | | | :-- | :-- | | **局域网** | 打开「在局域网共享」，给每个客户端一个命名的网关 key，各自设每天、每周或每月的 token 和花费上限 | -| **远程 magpie** | 笔记本用台式机上那个 magpie 的 provider、账号和路由组，同时照样配置自己的 Agent | -| **Docker** | 在服务器或 NAS 上跑 `ghcr.io/yetone/magpie`，用 Web 界面管理 | +| **[远程 magpie](https://usemagpie.ai/docs/zh/remote)** | 笔记本用台式机上那个 magpie 的 provider、账号和路由组，同时照样配置自己的 Agent | +| **[Docker](https://usemagpie.ai/docs/zh/docker)** | 在服务器或 NAS 上跑 `ghcr.io/yetone/magpie`，用 Web 界面管理 | | **同步** | 备份到文件，或者通过 WebDAV（坚果云、Nextcloud……）或 S3 在多台机器间同步 | ### 还有 @@ -272,6 +272,8 @@ magpie plugin options model-map '{"mapping": {"fast": "deepseek/deepseek-chat"}} | **[插件](https://usemagpie.ai/docs/zh/plugins)** | 使用插件和编写插件 | | **[意图路由](https://usemagpie.ai/docs/zh/intent)** | 按每轮对话的内容选择模型 | | **[导入链接](https://usemagpie.ai/docs/zh/import)** | 给 provider 网站用的「添加到 magpie」按钮 | +| **[远程 magpie](https://usemagpie.ai/docs/zh/remote)** | 在其他电脑上用同一个 magpie 的 provider 和路由组 | +| **[Docker](https://usemagpie.ai/docs/zh/docker)** | 在服务器或 NAS 上运行 magpie | ## 隐私 diff --git a/site/public/docs.css b/site/public/docs.css index 2a2f9c4e..d2b62288 100644 --- a/site/public/docs.css +++ b/site/public/docs.css @@ -69,6 +69,8 @@ nav .wrap { display: flex; align-items: center; gap: 14px; height: 60px; } nav .links { display: flex; gap: 24px; margin-left: auto; margin-right: 10px; font-size: 14px; color: var(--ink2); } nav .links a { text-decoration: none; } nav .links a:hover { color: var(--ink); } +/* listed in the contents (docs.js reads them from here) but kept out of the bar, which has no room */ +nav .links a.toc-only { display: none; } .icon-btn { display: inline-grid; place-items: center; width: 34px; height: 34px; border-radius: 8px; border: 1px solid var(--line); background: transparent; color: var(--ink2); cursor: pointer; padding: 0; flex: none; } .icon-btn:hover { color: var(--ink); } .icon-btn svg { width: 16px; height: 16px; } @@ -129,7 +131,7 @@ article :not(pre) > code { font-size: .86em; background: var(--code); border: 1p .figure figcaption { font-size: 13px; color: var(--ink3); margin-top: 12px; text-align: center; } .steps { counter-reset: s; list-style: none; padding: 0 !important; display: grid; gap: 1px; background: var(--line); border: 1px solid var(--line); border-radius: 14px; overflow: hidden; } -.steps li { counter-increment: s; background: var(--card); margin: 0 !important; padding: 18px 20px 18px 60px; position: relative; } +.steps li { counter-increment: s; background: var(--card); margin: 0 !important; padding: 18px 20px 18px 60px; position: relative; min-width: 0; } .steps li::before { content: counter(s); position: absolute; left: 20px; top: 18px; width: 24px; height: 24px; border-radius: 50%; border: 1px solid var(--line); display: grid; place-items: center; font-size: 12.5px; font-weight: 600; color: var(--ink); } .steps li b { display: block; margin-bottom: 2px; } diff --git a/site/public/docs/docker.html b/site/public/docs/docker.html new file mode 100644 index 00000000..5f060770 --- /dev/null +++ b/site/public/docs/docker.html @@ -0,0 +1,236 @@ + + + + + +Docker · magpie docs + + + + + + + + + + + + + + + + + + + + + +
+ + +
+

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.

+ +
+ + + + + +
Imageghcr.io/yetone/magpie, for linux/amd64 and linux/arm64
Tagslatest (the newest release), 0.1.1150 (one release), 0.1, edge (every change on main)
Ports3425 the gateway agents call; 3430 the browser UI, when the container runs magpie web
Volume/config: providers, keys, sign-ins, plugins and usage
Usernonroot (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:

+
+ 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
+
+

The log names the page with its key:

+
+ 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
+
+
Keep the ports on 127.0.0.1 for now. Until it is shared, a gateway in Docker answers anyone who reaches it, with any key (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.

+
Anyone with the link can change magpie and see its keys. The page has no HTTPS of its own. Keep 3430 on loopback or a VPN, or put it behind a reverse proxy with TLS.
+ +

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:

+
+ Shell + + 
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.

+
+ + + + + +
PathHolds
/config/magpiemagpie’s own files: settings.json, providers, gateway keys, routing groups
/config/homethe container’s HOME: sign-ins kept where their agent keeps them (~/.codex, ~/.claude…)
/config/cachethe model catalog, and Bun, which plugins run on (downloaded the first time one is used)
/config/data, /config/statethe 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

+
+ + + + + +
VariableWhat it does
MAGPIE_ADDRwhere the gateway listens. The image sets 0.0.0.0:3425, so the published port reaches it.
MAGPIE_PUBLIC_URLthe 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_KEYthe browser UI’s key, kept across restarts (16+ characters)
HOME, XDG_CONFIG_HOME, XDG_CACHE_HOME, XDG_DATA_HOME, XDG_STATE_HOMEset by the image to the folders under /config above; leave them
+ +

Share it with other machines

+
    +
  1. 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": true in /config/magpie/settings.json.
    2. +
  2. Give each client a keyGateway → Gateway keys, or in a terminal docker exec magpie magpie gateway-key add "Laptop", which prints the new sk-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).
    3. +
  3. 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.
    4. +
+

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.

+
Over the internet, prefer a VPN such as Tailscale or WireGuard to opening 3425. A reverse proxy or tunnel in front of the container is the network too: turn sharing on first, so that its clients need a gateway key.
+ +

Docker Compose on a NAS

+
+ compose.yaml + + 
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 healthcheck exits 0 while the gateway answers, under serve and web alike, so docker ps shows the container as healthy and Compose can wait for it with depends_on: condition: service_healthy.
    • +
  • Terminal. docker exec -it magpie bash, or a NAS panel’s terminal, opens a shell with magpie on its PATH: magpie providers, magpie models, magpie usage, magpie quota and 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, then docker rm -f magpie and the same docker run, or docker 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.

+
+
+ + + + + + + diff --git a/site/public/docs/import.html b/site/public/docs/import.html index b8c3996f..1d61afe9 100644 --- a/site/public/docs/import.html +++ b/site/public/docs/import.html @@ -46,6 +46,8 @@ Get started Intent routing Plugins + Remote magpie + Docker Add to magpie Integrate Releases @@ -255,6 +257,8 @@ href = "https://usemagpie.ai/import#" + urlencode({ Get started Intent routing Plugins + Remote magpie + Docker GitHub Discord Releases diff --git a/site/public/docs/integrate.html b/site/public/docs/integrate.html index 3d95f17e..d1aab8e7 100644 --- a/site/public/docs/integrate.html +++ b/site/public/docs/integrate.html @@ -45,6 +45,8 @@ Get started Intent routing Plugins + Remote magpie + Docker Add to magpie Integrate Releases @@ -147,6 +149,8 @@ curl -s http://127.0.0.1:3425/v1/models -H "Authorization: Bearer magpie-acme"Home Intent routing Plugins + Remote magpie + Docker Add to magpie Integrate GitHub diff --git a/site/public/docs/intent.html b/site/public/docs/intent.html index 46b130c2..ec76f56c 100644 --- a/site/public/docs/intent.html +++ b/site/public/docs/intent.html @@ -46,6 +46,8 @@ Get started Intent routing Plugins + Remote magpie + Docker Add to magpie Integrate Releases @@ -316,6 +318,8 @@ The number of its kind (0 for none): Home Intent routing Plugins + Remote magpie + Docker Add to magpie Integrate GitHub diff --git a/site/public/docs/ja/docker.html b/site/public/docs/ja/docker.html new file mode 100644 index 00000000..b85b20dd --- /dev/null +++ b/site/public/docs/ja/docker.html @@ -0,0 +1,236 @@ + + + + + +Docker · magpie ドキュメント + + + + + + + + + + + + + + + + + + + + + +
+ + +
+

ドキュメント · サーバー

+

Docker で magpie を動かす

+

デスクトップのないサーバーや NAS で magpie を動かします。そのゲートウェイがほかのコンピューターのエージェントにモデルを提供し、プロバイダの追加やサブスクリプションへのサインインはブラウザのページから行います。

+ +
+ + + + + +
イメージghcr.io/yetone/magpie（linux/amd64 と linux/arm64）
タグlatest（最新リリース）、0.1.1150（特定のリリース）、0.1、edge（main の変更ごと）
ポート3425 はエージェントが呼ぶゲートウェイ、3430 はコンテナが magpie web を動かすときのブラウザ UI
ボリューム/config：プロバイダ、キー、サインイン、プラグイン、使用量
ユーザーnonroot（uid 65532）
+

イメージに入っているのはターミナル専用ビルドの magpie で、distroless をベースに、コンテナ内でターミナルを使うための bash と busybox を含みます。コマンドを指定しなければ magpie serve（ゲートウェイのみ）を実行します。コンテナ内には設定するエージェントがないので、ここでの magpie はゲートウェイです。それを使うエージェントはほかのマシンで動きます。

+ +

起動する

+

ブラウザ UI 付きで、再起動しても変わらないページ用のキーを渡し、両方のポートをホストのループバックだけに公開して起動します。

+
+ 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
+
+

ログにキー付きのページのアドレスが出ます。

+
+ 出力 + 
● 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
+
+
今はポートを 127.0.0.1 のままにしてください。共有をオンにするまで、Docker 内のゲートウェイは届いた相手すべてに、どんなキー（Bearer magpie も含む）でも応答します。-p 3425:3425 はホストのすべてのインターフェイスに公開し、ホストのファイアウォールも通り抜けます。外に公開するのは、共有をオンにしてゲートウェイキーを用意してからにしてください。
+

web --addr 0.0.0.0:3430 --no-open を付けなければコンテナはゲートウェイだけを動かし、設定はコンテナ内のターミナルから行います（docker exec -it magpie magpie provider add …）。名前付きボリュームの代わりにフォルダを /config にバインドマウントすることもできます。uid 65532 が書き込める必要があります：sudo chown -R 65532:65532 /volume1/docker/magpie/config。

+ +

ブラウザ UI

+

ログのリンクを開きます。リンクのキーは cookie に置き換わり、アドレスから消えます。キーなしで開いたページは拒否されます（401）。MAGPIE_WEB_KEY（英数字か - . _ ~ で 16 文字以上。openssl rand -hex 16 で作れます）を設定すると、再起動してもキーは変わらず、ブラウザは 400 日サインインしたままです。設定しなければ起動のたびに新しいキーができ、cookie はそのブラウザセッションの間だけ有効です。

+

ページはゲートウェイモードで開きます：プロバイダ、ゲートウェイ、ルーティング、使用量、プラグイン、設定だけで、コンテナにはエージェントがないのでエージェント、セッション、ライブラリはありません。設定 → 一般 → ゲートウェイモードでオフにできます。

+

NAS や SSH で入るサーバーでは、3430 を公開せずにトンネル経由でページを開きます：ssh -L 3430:127.0.0.1:3430 you@nas を実行してから、自分のコンピューターでログのリンクを開きます。

+
リンクを持つ人は誰でも magpie を変更し、そのキーを見られます。ページ自体に HTTPS はありません。3430 はループバックか VPN 上に置くか、TLS 付きのリバースプロキシの後ろに置いてください。
+ +

サブスクリプションにサインイン

+

API キーはデスクトップと同じくプロバイダで追加します。サブスクリプション（ChatGPT、Claude…）のサインインはブラウザでベンダーのページを開き、終わるとベンダーはそのブラウザを localhost に戻します。ChatGPT なら http://localhost:1455/auth/callback?code=… です。これはコンテナではなく自分のコンピューターなので、ページは開けません。アドレスバーのアドレスを丸ごとコピーし、サインインの コールバック URL 欄に貼り付けます。

+

ターミナルからも同じことができます。

+
+ Shell + + 
docker exec -it magpie magpie accounts add codex
+
+

表示されたリンクを開いてサインインし、ブラウザが最後に表示したアドレスを貼り付けます。ブラウザ UI からはファイルからサインインを取り込むこともできます。

+ +

保存されるもの

+

magpie が書くものはすべて /config の下にあるので、再起動しても、同じボリュームで新しいコンテナを作っても、プロバイダ、キー、サインイン、プラグインは残ります。

+
+ + + + + +
パス中身
/config/magpiemagpie 自身のファイル：settings.json、プロバイダ、ゲートウェイキー、ルーティンググループ
/config/homeコンテナの HOME：サインインは各エージェントが保存する場所（~/.codex、~/.claude…）に保存されます
/config/cacheモデルカタログと、プラグインが動く Bun（初めてプラグインを使うときにダウンロード）
/config/data、/config/statemagpie が保存するその他のもの
+

古いイメージで作ったボリュームもそのまま使えます。magpie は起動時に足りないフォルダを作ります。古いイメージで行ったサインイン（ボリュームの外に保存されていたもの）だけはやり直しが必要です。

+ +

環境変数

+
+ + + + + +
変数役割
MAGPIE_ADDRゲートウェイが待ち受けるアドレス。イメージでは 0.0.0.0:3425 に設定され、公開したポートから届きます。
MAGPIE_PUBLIC_URLほかのマシンがゲートウェイに届くアドレス。例：http://192.168.1.20:3425（ホストや NAS のアドレスと公開ポート）、またはリバースプロキシのベース URL。コンテナ内の magpie には Docker 自身の 172.17.x のアドレスしか見えません。これを設定すると、表示されるアドレスが使うべきものになります。
MAGPIE_WEB_KEYブラウザ UI のキー。再起動しても変わりません（16 文字以上）
HOME、XDG_CONFIG_HOME、XDG_CACHE_HOME、XDG_DATA_HOME、XDG_STATE_HOMEイメージが上の /config 配下のフォルダに設定しています。変えないでください
+ +

ほかのマシンと共有する

+
    +
  1. 共有をオンにするブラウザ UI で 設定 → ローカルネットワークで共有 → オン。Magpie という名前のゲートウェイキーも作られます。以後、コンテナの外からのリクエストには有効なゲートウェイキーが必要で、ないものは 401 になります。UI を使わない場合は /config/magpie/settings.json に "lan": true を書きます。
    2. +
  2. クライアントごとにキーを渡すゲートウェイ → ゲートウェイキー、またはターミナルで docker exec magpie magpie gateway-key add "Laptop"。新しい sk-magpie-key-… が表示されます。キーごとに日・週・月の上限と使えるモデルを決められます（magpie gateway-key limit、magpie gateway-key models）。
    3. +
  3. ポートを公開する-p 3425:3425（または NAS の LAN や VPN のアドレスに限定して -p 192.168.1.20:3425:3425）と -e MAGPIE_PUBLIC_URL=http://192.168.1.20:3425 を付けてコンテナを作り直します。
    4. +
+

ほかのコンピューターでは、エージェントをゲートウェイに向け、そのキーのどれかを API キーにします：OpenAI クライアントなら http://192.168.1.20:3425/v1、Anthropic や Gemini なら http://192.168.1.20:3425。モデル ID は provider/model かルーティンググループの名前で、GET /v1/models が一覧を返します。そのコンピューターでも magpie を動かしているなら、コンテナをリモート magpie として追加すれば、magpie がエージェントを設定します。

+
インターネット越しなら VPN を（Tailscale や WireGuard など）。3425 を開けるより安全です。コンテナの前に置くリバースプロキシやトンネルもネットワークです。先に共有をオンにして、そのクライアントにゲートウェイキーが必要になるようにしてください。
+ +

NAS で Docker Compose

+
+ compose.yaml + + 
services:
+  magpie:
+    image: ghcr.io/yetone/magpie:latest
+    restart: unless-stopped
+    ports:
+      # 共有をオンにしてゲートウェイキーができるまではループバックのみ
+      - "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]
+
+

続いて sudo chown -R 65532:65532 ./config、docker compose up -d を実行し、SSH トンネル経由で http://127.0.0.1:3430/?k=<random-key> を開いて、プロバイダを追加し、ローカルネットワークで共有をオンにして、マシンごとにゲートウェイキーを作ります。そのあとゲートウェイの行を "3425:3425"（または NAS の LAN や VPN のアドレス）に変えて、もう一度 docker compose up -d を実行します。

+ +

ヘルスチェック・ターミナル・更新

+
    +
  • ヘルスチェック。イメージには HEALTHCHECK があります。ゲートウェイが応答している間 magpie healthcheck は 0 で終わり、serve でも web でも同じです。docker ps は healthy と表示し、Compose は depends_on: condition: service_healthy で待てます。
    • +
  • ターミナル。docker exec -it magpie bash や NAS の管理画面のターミナルで、magpie が PATH にあるシェルが開きます：magpie providers、magpie models、magpie usage、magpie quota など、CLI のすべてが使えます。
    • +
  • 更新。新しいイメージを取得し、同じボリュームでコンテナを作り直します：docker pull ghcr.io/yetone/magpie:latest のあと docker rm -f magpie と同じ docker run、または docker compose pull && docker compose up -d。
    • +
  • 自分でビルドする。リポジトリのチェックアウトで docker build -t magpie . を実行すると同じイメージができます。
    • +
+ +

質問や共有したいセットアップがあれば Discord へどうぞ。詳細はリファレンス（英語）にあります。

+
+
+ + + + + + + diff --git a/site/public/docs/ja/import.html b/site/public/docs/ja/import.html index 2226a8ad..a7b813b6 100644 --- a/site/public/docs/ja/import.html +++ b/site/public/docs/ja/import.html @@ -46,6 +46,8 @@ はじめに インテントルーティング プラグイン + リモート magpie + Docker magpie に追加 アプリ連携 リリース @@ -255,6 +257,8 @@ href = "https://usemagpie.ai/import#" + urlencode({ はじめに インテントルーティング プラグイン + リモート magpie + Docker GitHub Discord リリース diff --git a/site/public/docs/ja/intent.html b/site/public/docs/ja/intent.html index ac3103f0..960d1a4d 100644 --- a/site/public/docs/ja/intent.html +++ b/site/public/docs/ja/intent.html @@ -46,6 +46,8 @@ はじめに インテントルーティング プラグイン + リモート magpie + Docker magpie に追加 アプリ連携 リリース @@ -316,6 +318,8 @@ The number of its kind (0 for none): ホーム インテントルーティング プラグイン + リモート magpie + Docker magpie に追加 アプリ連携 GitHub diff --git a/site/public/docs/ja/plugins.html b/site/public/docs/ja/plugins.html index 4be65df5..33ff9334 100644 --- a/site/public/docs/ja/plugins.html +++ b/site/public/docs/ja/plugins.html @@ -46,6 +46,8 @@ はじめに インテントルーティング プラグイン + リモート magpie + Docker magpie に追加 アプリ連携 リリース @@ -709,6 +711,8 @@ magpie plugin options model-map '{"mapping": {"fast": "deepseek/deepseek-chat"}} ホーム インテントルーティング プラグイン + リモート magpie + Docker magpie に追加 アプリ連携 GitHub diff --git a/site/public/docs/ja/remote.html b/site/public/docs/ja/remote.html new file mode 100644 index 00000000..c4639455 --- /dev/null +++ b/site/public/docs/ja/remote.html @@ -0,0 +1,183 @@ + + + + + +リモート magpie · magpie ドキュメント + + + + + + + + + + + + + + + + + + + + + +
+ + +
+

ドキュメント · 共有

+

リモート magpie

+

1 つの magpie で複数のコンピューターをまかなえます。プロバイダを保存するコンピューター（デスクトップ、サーバー、Docker で動かす NAS）でサインインとプロバイダ・ルーティンググループの設定を一度だけ行い、ほかの各コンピューターではその magpie を 1 つのプロバイダとして追加します。それがリモート magpie（Remote magpie）です。

+ +
+ + + + + +
共有する magpieほかのコンピューターの magpie
プロバイダ、サブスクリプション、キーここに保存・サインインリモート magpie 経由で使う
ルーティンググループここで作るoffice/group/… として選ぶ
エージェント自分のもの引き続きこのコンピューターの magpie が設定
使用量とクォータここで集計・取得ここに表示（リモートの名前付き）
+

手元のコンピューターでも magpie は動き続けます。そのコンピューターのエージェントを設定し、モデルを選び、セッションを保存します。モデルだけがもう一方から来ます。

+ +

1. メインの magpie を共有する

+
    +
  1. 共有をオンにするプロバイダを保存しているコンピューターで 設定 → ローカルネットワークで共有 → オン。magpie はローカルネットワークで待ち受け、Magpie という名前のゲートウェイキーを作ります。スイッチの下の アドレス の行に、ほかのコンピューターから届くアドレス（例：http://192.168.1.20:3425）が表示されます。
    2. +
  2. コンピューターごとにキーを作るゲートウェイ → ゲートウェイキー、または magpie gateway-key add "Laptop"。sk-magpie-key-… が表示されます。キーごとに日・週・月の上限と使えるモデルを決められ、呼び出しはその名前で集計されます。
    3. +
+

共有がオフの間、デスクトップの magpie は自分のコンピューターでしか待ち受けず、ほかのコンピューターからは届きません。Docker の magpie は公開したポートから届きますが、キーを求めるようにするには同じスイッチをオンにする必要があります。Docker を参照してください。

+ +

2. ほかのコンピューターで追加する

+

手順 1 のアドレスとキーが必要です。次のどれでも追加できます。

+
    +
  • アプリ：プロバイダ タブで ＋ プロバイダを追加 を押し、Remote magpie を選んで、アドレスとキーを入力します。
    • +
  • TUI（magpie tui）：Providers ページで a を押し、Remote magpie を選んでアドレスとキーを入力します。その行で w はアドレスの変更、m は一覧の再取得です。
    • +
  • CLI：
    • +
+
+ Shell + + 
magpie provider add remote-magpie sk-magpie-key-… url=http://192.168.1.20:3425 id=office
+magpie models            # office/… が共有する magpie のモデル
+magpie provider refresh office   # 一覧を再取得
+
+

id= はこのコンピューターでのプロバイダ名で、モデル ID の先頭にもなります（office/…）。アドレスは 192.168.1.20:3425（http:// とみなされます）、末尾に /v1 を付けた形、ルートのどれでも構いません。magpie はどの場合もすべての API をそこにつなぎます。共有元のコンピューターごとに、別の id でリモート magpie を 1 つ追加します。

+ +

使えるもの

+
    +
  • そのモデル。向こうのエージェントに見えるとおりです：office/relay-a/claude-sonnet-5、ラベルは Claude Sonnet 5 · Relay A · office。ID は ID のままで、名前はラベルにだけ付きます。ほかのモデルと同じようにエージェントに選べます。
    • +
  • そのルーティンググループ。office/group/… として現れます。振り分けは共有する magpie 上で、そのアカウントを使って決まります。
    • +
  • すべての API。リクエストはエージェントが使った API のまま転送されます（Anthropic Messages とトークン計数、Responses、Chat Completions）。共有側のプロバイダが別の API でしか提供しないモデルは、変換が 1 回だけ行われ、両方のコンピューターで変換されることはありません。Responses は WebSocket ではなく HTTP（SSE を含む）で送られます。
    • +
  • 画像と動画。画像・動画モデルは自動で見つかり、向こうの画像生成・編集・動画 API を通して使えます。
    • +
  • System One。決定モデル（Jev、Clef、自分で名前を付けたモデル）は向こうの /v1/systemone につながり、チャットモデルではなく決定モデルとして現れます。新しいものはプロバイダの一覧を更新すると見つかります。office だけを指定すると一覧の最初の決定モデルに問い合わせます。
    • +
  • Embeddings と rerank は向こうの対応する API に送られます。エージェントの一覧ではリモートでの扱いのままです。一覧にあっても会話に使えるわけではありません。
    • +
  • 価格。各モデルは共有する magpie の計算どおり（向こうで手動設定した価格、なければプロバイダの定価）になるので、2 台の集計は一致します。このコンピューターで設定した価格が優先されます。
    • +
+ +

クォータと使用量

+

使用量ページ、メニューバー、magpie quota には、共有する magpie のサブスクリプションカードがその名前付きで（Codex · office、id office/codex）、向こうが最後に読んだ内容で表示されます。ベンダーに問い合わせるのはサインインを持つコンピューターだけです。このコンピューターでカードを更新すると、向こうがもう一度読みます（最大で 30 秒に 1 回）。Codex のリセットや WorkBuddy のチェックインは、向こうのコンピューターのアプリ、TUI、CLI で行います。

+

共有する magpie は、このコンピューターのリクエストを、送ってきたゲートウェイキーの名前と応答したアカウントで記録します。

+ +

うまくいかないとき

+
+ + + + + + +
表示対処
「magpie isn’t shared on the local network」または「remote magpie isn’t shared」そのコンピューターで ローカルネットワークで共有 をオンにする
「remote magpie didn’t take this key」（401）向こうの有効なゲートウェイキーを使う：向こうの ゲートウェイ → ゲートウェイキー
モデルで 403そのキーは一部のモデルしか使えない可能性があります。向こうで magpie gateway-key models <id> を実行すると確認・変更できます。office だけだとキーの許可に関係なく System One の最初の決定モデルに問い合わせます。完全な office/provider/model ID を使ってください
「couldn’t reach the remote magpie」アドレス、向こうで magpie が共有オンで動いているか、ファイアウォールがポートを通すかを確認する
System One のモデルがない、または「doesn’t share its quotas」向こうの magpie を更新し、こちらで一覧を更新する
+
外出先からは、Tailscale や WireGuard などの VPN 越しに、VPN 上のアドレスで共有する magpie に届くようにしてください。ポートをインターネットに開けないでください。
+ +

質問や共有したいセットアップがあれば Discord へどうぞ。詳細はリファレンス（英語）にあります。

+
+
+ + + + + + + diff --git a/site/public/docs/ja/start.html b/site/public/docs/ja/start.html index bb008f85..7d90aeea 100644 --- a/site/public/docs/ja/start.html +++ b/site/public/docs/ja/start.html @@ -46,6 +46,8 @@ はじめに インテントルーティング プラグイン + リモート magpie + Docker magpie に追加 アプリ連携 リリース @@ -284,6 +286,8 @@ IP-CIDR6,::1/128,DIRECT,no-resolve ホーム インテントルーティング プラグイン + リモート magpie + Docker magpie に追加 アプリ連携 GitHub diff --git a/site/public/docs/plugins.html b/site/public/docs/plugins.html index a5404919..5f671e1c 100644 --- a/site/public/docs/plugins.html +++ b/site/public/docs/plugins.html @@ -46,6 +46,8 @@ Get started Intent routing Plugins + Remote magpie + Docker Add to magpie Integrate Releases @@ -709,6 +711,8 @@ magpie plugin options model-map '{"mapping": {"fast": "deepseek/deepseek-chat"}} Home Intent routing Plugins + Remote magpie + Docker Add to magpie Integrate GitHub diff --git a/site/public/docs/remote.html b/site/public/docs/remote.html new file mode 100644 index 00000000..e6ade9f2 --- /dev/null +++ b/site/public/docs/remote.html @@ -0,0 +1,183 @@ + + + + + +Remote magpie · magpie docs + + + + + + + + + + + + + + + + + + + + + +
+ + +
+

Docs · Sharing

+

Remote magpie

+

One magpie can serve several computers. Sign in and set up providers and routing groups once, on the computer that keeps them (your desktop, a server, a NAS in Docker), and on every other computer add that magpie as a provider of its own: a Remote magpie.

+ +
+ + + + + +
The shared magpieEach other computer’s magpie
Providers, subscriptions, keyskept and signed in hereuses them through the Remote magpie
Routing groupsmade herepicked as office/group/…
Agentsits ownstill wired by this computer’s magpie
Usage and quotascounted and read hereshown here, named with the remote
+

The computer you sit at still runs magpie: it wires that computer’s agents, picks their models and keeps their sessions. Only the models come from the other one.

+ +

1. Share the main magpie

+
    +
  1. Turn on sharingOn the computer that keeps your providers: Settings → Share on local network → On. magpie then listens on the local network and makes a gateway key named Magpie. The Address row below the switch shows where other computers reach it, such as http://192.168.1.20:3425.
    2. +
  2. Make a key for each computerGateway → Gateway keys, or magpie gateway-key add "Laptop", which prints its sk-magpie-key-…. Each key can have its own daily, weekly or monthly limit and its own models, and its calls are counted under its name.
    3. +
+

While sharing is off, a desktop magpie listens on its own computer only, and other computers can’t reach it. A magpie in Docker is reached through its published port instead, and needs the same switch turned on before it asks for keys; see Docker.

+ +

2. Add it on the other computer

+

You need the address and a key from step 1. Any of these does it:

+
    +
  • The app: on the Providers tab press ＋ Add provider, pick Remote magpie, then give its address and the key.
    • +
  • The TUI (magpie tui): on the Providers page press a, pick Remote magpie, then type its address and key. On its row, w changes the address and m fetches its list again.
    • +
  • The CLI:
    • +
+
+ Shell + + 
magpie provider add remote-magpie sk-magpie-key-… url=http://192.168.1.20:3425 id=office
+magpie models            # office/… are the shared magpie's
+magpie provider refresh office   # fetch its list again
+
+

id= names the provider here, and so begins its models’ ids (office/…). The address can be typed as 192.168.1.20:3425 (plain http:// is assumed), with /v1 after it, or as the root: magpie puts every API on it either way. Add one Remote magpie for each computer you share from, with a different id.

+ +

What you get

+
    +
  • Its models, as its own agents are shown them: office/relay-a/claude-sonnet-5, labelled Claude Sonnet 5 · Relay A · office. The ids stay ids; only the labels carry the names. Pick them for an agent here like any other model.
    • +
  • Its routing groups, as office/group/…. The group decides on the shared magpie, with its accounts.
    • +
  • Every API. A request goes on in the API the agent spoke (Anthropic Messages and token counting, Responses, Chat Completions). A model that the shared magpie’s provider serves on another API only is turned into that API once, never on both computers. Responses go over HTTP, SSE included, not WebSocket.
    • +
  • Images and video. Its image and video models are found by themselves and served through its image generation and edit, and video, APIs.
    • +
  • System One. Its decision models (Jev, Clef, and models with names of your own) are set up at its /v1/systemone and appear as decision models, not chat models. Refresh the provider’s list to find new ones. A bare office asks the first decision model listed.
    • +
  • Embeddings and rerank go to its matching APIs. They stay in agents’ lists as they are on the remote; being listed doesn’t make them able to hold a conversation.
    • +
  • Prices. Each model costs here what the shared magpie counts it at (a price set there by hand, else its provider’s list price), so the two computers count the same. A price you set here comes first.
    • +
+ +

Quotas and usage

+

The Usage page, the menu bar and magpie quota show the shared magpie’s subscription cards, named with it (Codex · office, id office/codex), as that magpie last read them: only the computer with the sign-ins asks the vendors. A card’s refresh here has it read that card once more, at most once every 30 seconds. A Codex reset or a WorkBuddy check-in is pressed on that computer, from its own app, TUI or CLI.

+

The shared magpie counts this computer’s requests under the name of the gateway key it sends, with the account that answered.

+ +

When it doesn’t work

+
+ + + + + + +
You seeWhat to do
“magpie isn’t shared on the local network”, or “remote magpie isn’t shared”turn on Share on local network on that computer
“remote magpie didn’t take this key” (401)use one of its enabled gateway keys: Gateway → Gateway keys there
403 for a modelthat key may use only some models: magpie gateway-key models <id> on that computer shows or changes them. A bare office asks System One’s first decision model, whatever the key allows; use the full office/provider/model id
“couldn’t reach the remote magpie”check the address, that magpie is running there with sharing on, and that its firewall lets the port in
no System One models, or “doesn’t share its quotas”update magpie on that computer, then refresh the list here
+
Away from home, reach the shared magpie over a VPN such as Tailscale or WireGuard, with its address there. Don’t open its port to the internet.
+ +

Questions or a setup worth sharing? Ask on Discord. The reference has the details.

+
+
+ + + + + + + diff --git a/site/public/docs/start.html b/site/public/docs/start.html index da97db50..a8263d4b 100644 --- a/site/public/docs/start.html +++ b/site/public/docs/start.html @@ -46,6 +46,8 @@ Get started Intent routing Plugins + Remote magpie + Docker Add to magpie Integrate Releases @@ -284,6 +286,8 @@ IP-CIDR6,::1/128,DIRECT,no-resolve Home Intent routing Plugins + Remote magpie + Docker Add to magpie Integrate GitHub diff --git a/site/public/docs/zh/docker.html b/site/public/docs/zh/docker.html new file mode 100644 index 00000000..f1c443a3 --- /dev/null +++ b/site/public/docs/zh/docker.html @@ -0,0 +1,236 @@ + + + + + +Docker · magpie 文档 + + + + + + + + + + + + + + + + + + + + + +
+ + +
+

文档 · 服务器

+

在 Docker 里运行 magpie

+

在没有桌面的服务器或 NAS 上运行 magpie：它的网关为其他电脑上的 Agent 提供模型，供应商的添加和订阅登录都在浏览器页面里完成。

+ +
+ + + + + +
镜像ghcr.io/yetone/magpie，支持 linux/amd64 和 linux/arm64
标签latest（最新正式版）、0.1.1150（某个版本）、0.1、edge（main 上的每次改动）
端口3425 是 Agent 调用的网关；3430 是容器运行 magpie web 时的 Web 界面
数据卷/config：供应商、密钥、登录、插件和用量
用户nonroot（uid 65532）
+

镜像里是 magpie 的纯终端版本，基于 distroless，并带了 bash 和 busybox，方便在容器里开终端。不指定命令时运行 magpie serve（只有网关）。容器里找不到需要配置的 Agent，所以这里的 magpie 是一个网关：用它的 Agent 运行在别的机器上。

+ +

运行

+

带 Web 界面运行，给页面一个重启后不变的 key，两个端口都只发布在宿主机的回环地址上：

+
+ 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
+
+

日志里给出带 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
+
+
端口先留在 127.0.0.1 上。在打开共享之前，Docker 里的网关对任何能访问到它的人、任何 key（包括 Bearer magpie）都会应答。-p 3425:3425 会把它发布到宿主机的所有网卡上，绕过宿主机防火墙。等共享打开、有了网关密钥之后再往外发布。
+

不加 web --addr 0.0.0.0:3430 --no-open 时容器只跑网关，需要在容器终端里配置（docker exec -it magpie magpie provider add …）。也可以把一个目录绑定挂载到 /config 来代替命名卷，前提是 uid 65532 能写它：sudo chown -R 65532:65532 /volume1/docker/magpie/config。

+ +

Web 界面

+

打开日志里的链接。链接里的 key 会换成一个 cookie，并从地址栏里去掉；不带 key 打开会被拒绝（401）。设置了 MAGPIE_WEB_KEY（16 个以上的字母、数字或 - . _ ~；openssl rand -hex 16 可以生成一个）时，重启后 key 不变，浏览器保持登录 400 天。不设置时每次启动都会生成新 key，cookie 只在本次浏览器会话里有效。

+

这个页面处于网关模式：只有 供应商、网关、路由、用量、插件和 设置，没有 Agent、会话和资源库，因为容器里没有 Agent。设置 → 常规 → 网关模式 可以关掉它。

+

NAS 或通过 SSH 访问的服务器上，用隧道打开页面，不要发布 3430：ssh -L 3430:127.0.0.1:3430 you@nas，然后在自己电脑上打开日志里的链接。

+
拿到链接的人都能修改 magpie、看到它的密钥。页面本身没有 HTTPS。让 3430 只在回环地址或 VPN 上，或者放在带 TLS 的反向代理后面。
+ +

登录订阅

+

在 供应商 里添加 API key，和桌面版一样。订阅登录（ChatGPT、Claude……）会在你的浏览器里打开厂商页面，完成后厂商把浏览器跳回 localhost，ChatGPT 是 http://localhost:1455/auth/callback?code=…。那是你自己的电脑，不是容器，所以页面打不开。把地址栏里的完整地址复制下来，粘贴到登录的 回调 URL 一栏。

+

在终端里也可以：

+
+ Shell + + 
docker exec -it magpie magpie accounts add codex
+
+

打开它打印的链接并登录，再把浏览器最后停在的地址粘贴回去。Web 界面也能从文件导入登录。

+ +

保存了什么

+

magpie 写的所有东西都在 /config 下，所以重启、或者在同一个数据卷上新建容器，供应商、密钥、登录和插件都还在。

+
+ + + + + +
路径内容
/config/magpiemagpie 自己的文件：settings.json、供应商、网关密钥、路由组
/config/home容器的 HOME：登录保存在对应 Agent 保存的位置（~/.codex、~/.claude……）
/config/cache模型目录，以及插件运行用的 Bun（第一次用插件时下载）
/config/data、/config/statemagpie 保存的其他内容
+

旧镜像创建的数据卷照样能用：magpie 启动时会补上缺的目录。只有用旧镜像做的登录（当时存在数据卷之外）需要重新登录。

+ +

环境变量

+
+ + + + + +
变量作用
MAGPIE_ADDR网关监听的地址。镜像里设为 0.0.0.0:3425，发布的端口才能访问到它。
MAGPIE_PUBLIC_URL其他机器访问网关用的地址，例如 http://192.168.1.20:3425（宿主机或 NAS 的地址，加发布的端口），或反向代理的 base URL。容器里 magpie 只看得到 Docker 自己的 172.17.x 地址；设置后，它显示和打印的就是该用的地址。
MAGPIE_WEB_KEYWeb 界面的 key，重启后不变（16 个字符以上）
HOME、XDG_CONFIG_HOME、XDG_CACHE_HOME、XDG_DATA_HOME、XDG_STATE_HOME镜像已设为上面 /config 下的目录，不要改
+ +

给其他机器共享

+
    +
  1. 打开共享在 Web 界面里：设置 → 局域网共享 → 开启。同时会生成一个名为 Magpie 的网关密钥。此后容器外的每个请求都必须带一个启用的网关密钥，不带的返回 401。不用界面的话，在 /config/magpie/settings.json 里写 "lan": true。
    2. +
  2. 给每个客户端一个密钥网关 → 网关密钥，或在终端里 docker exec magpie magpie gateway-key add "Laptop"，它会打印新的 sk-magpie-key-…。每个密钥可以有自己的每日、每周或每月上限和可用模型（magpie gateway-key limit、magpie gateway-key models）。
    3. +
  3. 发布端口用 -p 3425:3425（或绑定到 NAS 的局域网或 VPN 地址，-p 192.168.1.20:3425:3425）并加上 -e MAGPIE_PUBLIC_URL=http://192.168.1.20:3425 重新创建容器。
    4. +
+

在其他电脑上，把 Agent 指向这个网关，用其中一个密钥作为 API key：OpenAI 客户端用 http://192.168.1.20:3425/v1，Anthropic 或 Gemini 客户端用 http://192.168.1.20:3425。模型 id 是 provider/model 或路由组的名字，GET /v1/models 会列出它们。如果那台电脑自己也运行 magpie，就把容器添加为远程 magpie，由 magpie 替你配置 Agent。

+
跨互联网访问时，优先用 VPN（如 Tailscale 或 WireGuard），不要直接开放 3425。容器前面的反向代理或隧道也算网络：先打开共享，这样它的客户端才必须带网关密钥。
+ +

在 NAS 上用 Docker Compose

+
+ compose.yaml + + 
services:
+  magpie:
+    image: ghcr.io/yetone/magpie:latest
+    restart: unless-stopped
+    ports:
+      # 打开共享并有了网关密钥之前，只发布在回环地址上
+      - "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]
+
+

然后：sudo chown -R 65532:65532 ./config，docker compose up -d，通过 SSH 隧道打开 http://127.0.0.1:3430/?k=<random-key>，添加供应商，打开 局域网共享，给每台机器生成一个网关密钥。再把网关那一行改成 "3425:3425"（或 NAS 的局域网、VPN 地址），重新 docker compose up -d。

+ +

健康检查、终端与更新

+
    +
  • 健康检查。镜像带 HEALTHCHECK：网关能应答时 magpie healthcheck 返回 0，serve 和 web 都一样，所以 docker ps 会显示 healthy，Compose 可以用 depends_on: condition: service_healthy 等它。
    • +
  • 终端。docker exec -it magpie bash 或 NAS 面板里的终端会打开一个 shell，magpie 在 PATH 里：magpie providers、magpie models、magpie usage、magpie quota 以及其他 CLI 命令。
    • +
  • 更新。拉取新镜像，在同一个数据卷上重新创建容器：docker pull ghcr.io/yetone/magpie:latest，然后 docker rm -f magpie 再执行同样的 docker run；或 docker compose pull && docker compose up -d。
    • +
  • 自己构建。在仓库的检出目录里 docker build -t magpie . 得到同样的镜像。
    • +
+ +

遇到问题，或者有值得分享的配置？来 Discord 聊。细节见参考文档（英文）。

+
+
+ + + + + + + diff --git a/site/public/docs/zh/import.html b/site/public/docs/zh/import.html index f2379084..3656b578 100644 --- a/site/public/docs/zh/import.html +++ b/site/public/docs/zh/import.html @@ -46,6 +46,8 @@ 快速上手 意图路由 插件开发 + 远程 magpie + Docker Add to magpie 接入应用 版本发布 @@ -255,6 +257,8 @@ href = "https://usemagpie.ai/import#" + urlencode({ 快速上手 意图路由 插件开发 + 远程 magpie + Docker GitHub Discord 版本发布 diff --git a/site/public/docs/zh/integrate.html b/site/public/docs/zh/integrate.html index b340d4bf..b2800fbe 100644 --- a/site/public/docs/zh/integrate.html +++ b/site/public/docs/zh/integrate.html @@ -45,6 +45,8 @@ 快速上手 意图路由 插件开发 + 远程 magpie + Docker Add to magpie 接入应用 版本发布 @@ -147,6 +149,8 @@ curl -s http://127.0.0.1:3425/v1/models -H "Authorization: Bearer magpie-acme"首页 意图路由 插件开发 + 远程 magpie + Docker Add to magpie 接入应用 GitHub diff --git a/site/public/docs/zh/intent.html b/site/public/docs/zh/intent.html index 3c16a82d..584730f1 100644 --- a/site/public/docs/zh/intent.html +++ b/site/public/docs/zh/intent.html @@ -46,6 +46,8 @@ 快速上手 意图路由 插件开发 + 远程 magpie + Docker Add to magpie 接入应用 版本发布 @@ -316,6 +318,8 @@ The number of its kind (0 for none): 首页 意图路由 插件开发 + 远程 magpie + Docker Add to magpie 接入应用 GitHub diff --git a/site/public/docs/zh/plugins.html b/site/public/docs/zh/plugins.html index 59193d32..17b59b90 100644 --- a/site/public/docs/zh/plugins.html +++ b/site/public/docs/zh/plugins.html @@ -46,6 +46,8 @@ 快速上手 意图路由 插件开发 + 远程 magpie + Docker Add to magpie 接入应用 版本发布 @@ -709,6 +711,8 @@ magpie plugin options model-map '{"mapping": {"fast": "deepseek/deepseek-chat"}} 首页 意图路由 插件开发 + 远程 magpie + Docker Add to magpie 接入应用 GitHub diff --git a/site/public/docs/zh/remote.html b/site/public/docs/zh/remote.html new file mode 100644 index 00000000..16dc31f3 --- /dev/null +++ b/site/public/docs/zh/remote.html @@ -0,0 +1,183 @@ + + + + + +远程 magpie · magpie 文档 + + + + + + + + + + + + + + + + + + + + + +
+ + +
+

文档 · 共享

+

远程 magpie

+

一个 magpie 可以服务多台电脑。在保存供应商的那台电脑上（你的台式机、一台服务器、Docker 里的 NAS）登录、配置一次供应商和路由组，然后在其他每台电脑上把这个 magpie 添加为一个供应商：远程 magpie（Remote magpie）。

+ +
+ + + + + +
共享的 magpie其他电脑上的 magpie
供应商、订阅、密钥保存并登录在这里通过远程 magpie 使用
路由组在这里创建以 office/group/… 选用
Agent它自己的仍由本机的 magpie 配置
用量与额度在这里统计和读取在这里显示，带上远程的名字
+

你面前的电脑仍然运行 magpie：它配置本机的 Agent、为它们选模型、保存它们的会话。只有模型来自另一台。

+ +

1. 共享主 magpie

+
    +
  1. 打开共享在保存供应商的电脑上：设置 → 局域网共享 → 开启。magpie 随即在局域网上监听，并生成一个名为 Magpie 的网关密钥。开关下方的 地址 一行显示其他电脑访问它的地址，例如 http://192.168.1.20:3425。
    2. +
  2. 给每台电脑一个密钥网关 → 网关密钥，或 magpie gateway-key add "Laptop"，它会打印 sk-magpie-key-…。每个密钥可以有自己的每日、每周或每月上限和可用模型，它的调用按它的名字统计。
    3. +
+

共享关闭时，桌面版 magpie 只在本机监听，其他电脑访问不到。Docker 里的 magpie 则通过发布的端口访问，同样要打开这个开关才会要求密钥；见 Docker。

+ +

2. 在其他电脑上添加

+

需要第 1 步里的地址和一个密钥。以下任一方式都可以：

+
    +
  • 应用：在 供应商 页按 ＋ 添加供应商，选 Remote magpie，填入地址和密钥。
    • +
  • TUI（magpie tui）：在 Providers 页按 a，选 Remote magpie，输入地址和密钥。在它那一行，w 修改地址，m 重新获取列表。
    • +
  • CLI：
    • +
+
+ Shell + + 
magpie provider add remote-magpie sk-magpie-key-… url=http://192.168.1.20:3425 id=office
+magpie models            # office/… 是共享 magpie 的模型
+magpie provider refresh office   # 重新获取列表
+
+

id= 是这个供应商在本机的名字，也是它的模型 id 的开头（office/…）。地址可以写成 192.168.1.20:3425（默认 http://），后面带 /v1，或者写根地址：magpie 都会把各个 API 接到上面。每台共享出来的电脑添加一个远程 magpie，用不同的 id。

+ +

能用到什么

+
    +
  • 它的模型，和它自己的 Agent 看到的一样：office/relay-a/claude-sonnet-5，标签是 Claude Sonnet 5 · Relay A · office。id 不变，名字只出现在标签里。在本机像其他模型一样为 Agent 选用。
    • +
  • 它的路由组，以 office/group/… 出现。路由在共享的 magpie 上用它的账号决定。
    • +
  • 所有 API。请求按 Agent 使用的 API 原样转发（Anthropic Messages 和 token 计数、Responses、Chat Completions）。共享 magpie 的供应商只用另一种 API 提供的模型，只转换一次，不会在两台电脑上各转一次。Responses 走 HTTP（包括 SSE），不走 WebSocket。
    • +
  • 图像和视频。它的图像和视频模型会被自动识别，经由它的图像生成、编辑和视频 API 提供。
    • +
  • System One。它的决策模型（Jev、Clef，以及你自己命名的模型）接到它的 /v1/systemone，作为决策模型而不是对话模型出现。刷新供应商列表可以发现新的。只写 office 时使用列表里的第一个决策模型。
    • +
  • Embeddings 和 rerank 发往它对应的 API。它们在 Agent 列表里保持远程上的样子；出现在列表里并不代表能用来对话。
    • +
  • 价格。每个模型在本机按共享 magpie 的计价（那边手动设的价格，否则是供应商的标价），两台电脑算出来一样。在本机设的价格优先。
    • +
+ +

额度与用量

+

用量页、菜单栏和 magpie quota 会显示共享 magpie 的订阅卡片，带上它的名字（Codex · office，id office/codex），内容是那边最近一次读取的结果：只有保存登录的电脑去问厂商。在本机刷新卡片会让那边再读一次，最多每 30 秒一次。Codex 重置或 WorkBuddy 签到要在那台电脑上，用它自己的应用、TUI 或 CLI 来做。

+

共享的 magpie 把本机的请求记在本机所用网关密钥的名字下，并记下应答的账号。

+ +

出问题时

+
+ + + + + + +
看到的提示怎么做
“magpie isn’t shared on the local network” 或 “remote magpie isn’t shared”在那台电脑上打开 局域网共享
“remote magpie didn’t take this key”（401）用它的一个已启用的网关密钥：那边的 网关 → 网关密钥
某个模型 403这个密钥可能只能用部分模型：在那台电脑上用 magpie gateway-key models <id> 查看或修改。只写 office 会请求 System One 的第一个决策模型，不管密钥允许什么；请用完整的 office/provider/model id
“couldn’t reach the remote magpie”检查地址、那边的 magpie 是否在运行并打开了共享、防火墙是否放行该端口
没有 System One 模型，或 “doesn’t share its quotas”更新那台电脑上的 magpie，再在本机刷新列表
+
不在家时，通过 Tailscale 或 WireGuard 等 VPN、用它在 VPN 里的地址访问共享的 magpie。不要把它的端口开放到互联网。
+ +

遇到问题，或者有值得分享的配置？来 Discord 聊。细节见参考文档（英文）。

+
+
+ + + + + + + diff --git a/site/public/docs/zh/start.html b/site/public/docs/zh/start.html index b7a7f1bc..b15f14ba 100644 --- a/site/public/docs/zh/start.html +++ b/site/public/docs/zh/start.html @@ -46,6 +46,8 @@ 快速上手 意图路由 插件开发 + 远程 magpie + Docker Add to magpie 接入应用 版本发布 @@ -284,6 +286,8 @@ IP-CIDR6,::1/128,DIRECT,no-resolve 首页 意图路由 插件开发 + 远程 magpie + Docker Add to magpie 接入应用 GitHub