Takuto Core の拡張

公式イメージに焼き込まれていないツールが必要になることはよくあります — kubectl、 terraform、社内ベンダーの CLI、あるいは固定バージョンの claude など。Takuto Core には 3 層の拡張モデル に加えて、ランタイムのみの微調整のための 4 つ目の方法があります。 ニーズに合うものを選んでください。

ニーズ仕組みどこに書くか
単一バイナリの CLI を追加（kubectl、terraform、ベンダー CLI）Provisioningconfig.toml の [provisioning].install_commands
焼き込み済みツールを特定バージョンに固定Provisioning（PATH シャドーイング）[provisioning].install_commands
システムパッケージ（apt）やライブラリを追加カスタム Dockerfile新しい Dockerfile FROM ghcr.io/takuto-team/takuto-core:latest
環境変数をどこでも追加Compose オーバーライドdocker-compose.override.yml
追加のホストディレクトリをマウントCompose オーバーライドdocker-compose.override.yml

指針となる原則: Baked = 宣伝された機能に必須、Provisioning = admin の好み、 カスタムイメージ = 特殊な OS レベルのニーズ。

仕組み 1 — [provisioning].install_commands

最も一般的なケースです。Takuto の起動ごとに、エントリポイントは SHA でゲートされた インストールパスを実行します:

  1. install_commands リストをハッシュ化します。
  2. ハッシュが前回の成功実行と一致すれば → スキップ（高速パス。変更がなければ毎回の起動で実行）。
  3. 異なれば → MAESTRO_TOOLS_BIN=/opt/maestro-tools/bin をエクスポートし、各コマンドを root として bash -c 経由で実行します。コマンドごとの失敗は警告をログに記録しますが 中断はしません。新しいハッシュは完全に成功したときだけ記録されるので、部分的な失敗は 次回の起動で再試行されます。

ツールは maestro-tools Docker ボリュームに置かれ、すべてのワーカー、エディター、実行コマンドの container に 読み取り専用 でバインドマウントされます。/opt/maestro-tools/bin が $PATH の 先頭 に来るので、そこに置いたものはどこでも使え、かつ 同名の焼き込みツールをシャドーします。

冪等性はあなたの責任

リストが変わるたびに再実行されます — コマンドを 追加 したときも（既存のものも再実行されます）。 各コマンドを存在チェックでガードしてください:

[provisioning]
install_commands = [
  '[ -f "$MAESTRO_TOOLS_BIN/kubectl" ] || (curl -fsSLo "$MAESTRO_TOOLS_BIN/kubectl" https://dl.k8s.io/release/v1.31.0/bin/linux/amd64/kubectl && chmod +x "$MAESTRO_TOOLS_BIN/kubectl")',
]

再起動後は、どの workflow も kubectl を直接呼べます。

claude を特定バージョンに固定する

[provisioning]
install_commands = [
  '[ -f "$MAESTRO_TOOLS_BIN/claude" ] || (npm install -g --prefix "$MAESTRO_TOOLS_BIN/.npm" @anthropic-ai/claude-code@2.1.140 && ln -sf "$MAESTRO_TOOLS_BIN/.npm/bin/claude" "$MAESTRO_TOOLS_BIN/claude")',
]

PATH の優先順位により、固定バージョンが焼き込みの @latest に勝ちます。元に戻すには: 行を削除し、再起動して、rm /opt/maestro-tools/bin/claude します。

プライベートなベンダー CLI をインストールする

install_commands = [
  '[ -f "$MAESTRO_TOOLS_BIN/mycli" ] || curl -fsSL -H "Authorization: token $MYCO_TOKEN" https://internal.example.com/cli/mycli-v2.tgz | tar -xz -C "$MAESTRO_TOOLS_BIN"',
]

インストールコマンドが参照できるよう、MYCO_TOKEN を takuto.env に設定してください。

設定を変えずに再インストールを強制する

SHA ゲートは、リストが変わっていなければ再実行をスキップします。強制するには（例: バイナリが 壊れていると疑う場合）:

docker exec --user root maestro-core-maestro-1 \
    rm /opt/maestro-tools/.provisioning-sha
docker compose restart maestro

すべてのカスタマイズを消去する

docker compose down
docker volume rm maestro-core_maestro-tools
docker compose up -d

仕組み 2 — カスタム Dockerfile

これは システムパッケージ（apt ライブラリ、デーモン）や、複数の OS ディレクトリ （/etc、/usr/share、/var/lib）に触れるものに使います。maestro-tools ボリュームは 単一の bin/ ディレクトリしか書かないので、システム全体へのインストールには provisioning は 不適切です。

# my-takuto.Dockerfile
FROM ghcr.io/takuto-team/takuto-core:latest
USER root
RUN apt-get update && apt-get install -y --no-install-recommends \
        awscli postgresql-client \
    && rm -rf /var/lib/apt/lists/*
USER maestro

docker-compose.yml に組み込みます:

services:
  maestro:
    build:
      context: .
      dockerfile: my-takuto.Dockerfile

その後 docker compose build maestro && docker compose up -d。

仕組み 3 — docker-compose.override.yml

Compose は docker-compose.override.yml を自動的にマージします。リビルドを必要としない ランタイムのみの微調整に使ってください。

追加の環境変数:

services:
  maestro:
    environment:
      - GH_HOST=github.example.com   # internal GHE instance
      - MY_API_TOKEN=...

追加のバインドマウント:

services:
  maestro:
    volumes:
      - /host/shared-cache:/home/maestro/.cache/shared:ro

Compose のオーバーライドは maestro サービスにのみ影響します。マウントや環境変数を spawn されたワーカー container に伝播させるには、エンジン内のワーカーボリューム / パススルー環境のリストにそれらを含める必要があります — Takuto Core のソースで WORKER_VOLUMES と PASSTHROUGH_ENV を参照してください。

ツール一覧の概要

  • Baked（宣伝された機能に必須）: node、npm、Rust ツールチェーン （cargo/rustfmt/clippy）、git、gh、acli、jq、docker CLI、iptables、 claude、cursor-agent、codex、opencode、openvscode-server、mise、そして Playwright/Chromium のライブラリ。
  • Provisioning デフォルト（admin が固定/置換/無効化できる）: Figma や Lokalise の CLI の ような単一バイナリツール。
  • Removed（カスタムイメージで対応）: 一部のデプロイでしか必要としない AWS CLI v2 のような ツール。

provisioning のトラブルシューティング

  • 「再起動でコマンドが実行されない。」 SHA ゲートは変わらないリストをスキップします — 何か（コメントでも）編集してハッシュを変えるか、rm /opt/maestro-tools/.provisioning-sha して 再起動してください。
  • 「ワーカーがツールを見つけられない。」 ツールがボリュームに置かれたか （docker exec maestro-core-maestro-1 ls /opt/maestro-tools/bin/）、/opt/maestro-tools/bin が ワーカーの $PATH の先頭にあるかを確認してください。インストール失敗については起動ログの [maestro-provisioning] … WARN 行を探してください。

詳しくは トラブルシューティング を参照してください。