ドキュメント · サーバー

Docker で magpie を動かす

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

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

起動する

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

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

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 を実行してから、自分のコンピューターでログのリンクを開きます。

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

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

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

docker exec -it magpie magpie accounts add codex

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

保存されるもの

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

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

環境変数

ゲートウェイキーとほかのマシン

1. クライアントごとにキーを作るゲートウェイ → ゲートウェイキー、またはターミナルで docker exec magpie magpie gateway-key add "Laptop"。新しい sk-magpie-key-… が表示されます。コンテナの外からのリクエストは、ホスト自身のものも含め、有効なゲートウェイキーが必要で、ないものは 401 になります。キーごとに日・週・月の上限と使えるモデルを決められます（magpie gateway-key limit、magpie gateway-key models）。
2. ポートを公開する-p 3425:3425（または NAS の LAN や VPN のアドレスに限定して -p 192.168.1.20:3425:3425）と -e MAGPIE_PUBLIC_URL=http://192.168.1.20:3425 を付けてコンテナを作り直します。

ほかのコンピューターでは、エージェントをゲートウェイに向け、そのキーのどれかを 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 がエージェントを設定します。

コンテナでは 設定 → ローカルネットワークで共有 は不要です。オンにすると Magpie という名前のゲートウェイキーも作られますが、ゲートウェイはどちらでもコンテナの外からのリクエストにキーを求めます。

以前のイメージからの更新。コンテナの外から magpie や、有効なゲートウェイキーではないキーを送るエージェントは、401（“the API key sent is not an enabled magpie gateway key”）を受け取るようになります。上の手順でキーを作り、エージェントの設定に入れてください。すでにゲートウェイキーを送っているエージェントや、ゲートウェイキーで追加したリモート magpie はそのまま動きます。

NAS で Docker Compose

services:
  magpie:
    image: ghcr.io/yetone/magpie:latest
    restart: unless-stopped
    ports:
      # 127.0.0.1: ホストのみ。コンテナの外の呼び出しにはゲートウェイキーが必要
      - "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 へどうぞ。詳細はリファレンス（英語）にあります。