Docker

サイドカーはマルチアーキテクチャのイメージ（linux/amd64、linux/arm64）として ghcr.io/miraistudio/spendctl で公開しています。中身は npm パッケージ spendctl と同じファイルに本番用の依存を加えたもので、非 root ユーザーで動き、状態はすべて /data の下に置きます。タグは 0.2.0、0.2（パッチリリースで更新）、latest の3つです。本番では少なくともマイナーバージョンまで固定してください。ライセンスは npm パッケージと同じです（イメージ内の /app/LICENSE）。

サイドカーを起動する

spendctl.yaml を置くディレクトリを /data にマウントします。

mkdir spend-demo && cd spend-demo
docker run --rm -v "$PWD:/data" ghcr.io/miraistudio/spendctl:0.2 init
docker run -d --name spendctl -v "$PWD:/data" -p 127.0.0.1:8402:8402 ghcr.io/miraistudio/spendctl:0.2

イメージの既定コマンドは start --host 0.0.0.0 なので、サイドカーはコンテナの外からの接続を受け付けます。ポートはエージェントがいる場所にだけ公開してください。127.0.0.1:8402:8402 ならホスト内に留まります。エージェントは 組み込み方 のとおり http://localhost:8402 にリクエストを送るだけです。ダッシュボードは http://localhost:8402/_spendctl/dashboard にあります。

人間側のコマンド

pending、approve、budget、ledger、export は動いているサイドカーに問い合わせ、管理トークンを .spendctl/ から読みます。同じマウントで、サイドカーのネットワーク名前空間の中で実行してください。

alias spendctl='docker run --rm --network container:spendctl -v "$PWD:/data" ghcr.io/miraistudio/spendctl:0.2'
spendctl pending
spendctl approve --latest
spendctl budget
spendctl export --format csv --out receipts.csv    # $PWD に書き出されます

ホストに Node.js があるなら、同じディレクトリで npx spendctl pending としても動きます。イメージにはコンテナの PATH 上に spendctl が入っているので、docker exec spendctl spendctl pending のように、動いているサイドカーのコンテナの中で直接実行することもできます。

クイックスタートを Docker だけで

モックのファシリテータと有料 API 2本もサイドカーのネットワーク名前空間に同居させると、どこから見ても localhost が同じ意味になります。

docker run -d --name spendctl-mock --network container:spendctl -v "$PWD:/data" ghcr.io/miraistudio/spendctl:0.2 mock
spendctl fetch "http://localhost:4021/weather?city=Tokyo" --agent researcher
# ✔ 200 paid $0.01

あとは クイックスタート の「何回か繰り返してください」から、npx spendctl を上の alias に読み替えて進めてください。

Docker Compose

services:
  spendctl:
    image: ghcr.io/miraistudio/spendctl:0.2
    volumes: ["./:/data"]
    ports: ["127.0.0.1:8402:8402"]
    restart: unless-stopped
  agent:
    build: .
    environment:
      SPENDCTL_URL: http://spendctl:8402    # @spendctl/client と spendctl CLI が読みます
    depends_on: [spendctl]

他のコンテナからサイドカーに届くようになったら、エージェントの識別はヘッダではなくトークンにしてください。spendctl.yaml で agentAuth: token にし、spendctl token <agent> でトークンを発行します（ポリシーリファレンス）。

Linux ホスト

コンテナは uid 100 で動きます。Linux ではバインドマウントしたディレクトリの所有者はあなたのユーザーなので、サイドカーが .spendctl/ に書けるよう、各 docker run に --user "$(id -u):$(id -g)"（Compose なら user:）を付けてください。macOS / Windows の Docker Desktop は所有者の対応付けを自動でやってくれます。

更新

新しいタグを pull してコンテナを作り直すだけです。台帳とトークンはホスト側の .spendctl/ にあるので失われません。

docker pull ghcr.io/miraistudio/spendctl:0.2
docker rm -f spendctl && docker run -d --name spendctl -v "$PWD:/data" -p 127.0.0.1:8402:8402 ghcr.io/miraistudio/spendctl:0.2