colab-fleet

重いCPU/ML作業を無料のGoogle Colabにオフロードして、Claude Code（または任意のMCPクライアント）から利用できるようにします。無料枠ロック、自動ティアダウン、ジョブキュー、チェックポイント再開を備えています。

English · 한국어

高価な処理（MLトレーニング、ハイパーパラメータスイープ、バックテスト）を、自分のマシンではなく無料のGoogle Colabランタイムで実行し、成果物だけを取り戻します。MCPクライアント（Claude Code、pi、…）が単一のツール呼び出し（gpu_submit(...)）でジョブを送信し、完了時に結果が自動的に取得されます。

ローカルにGPUや重いライブラリは不要です。無料のColabアカウントで十分です。

公式のcolab CLIとはどう違うのか？

一言で言うと、Googleのcolab CLIは人間がタイプするツールであり、colab-fleetはAIが呼び出すツールです。同じエンジン（公式CLI）に、ガードレールと自動化を重ねたものです。

GoogleはMCPサーバーを提供していません。コマンドラインCLIのみです。このプロジェクトはそれをラップして、エージェントが直接操作できるようにします。

例えるなら、公式CLIはマニュアルトランスミッション、colab-fleetは同じエンジン（無料のColabランタイム）にオートマチック＋シートベルト＋ナビゲーションを備えたものです。

Related MCP server: mcp-colab-gpu

インストール（3ステップ）

git clone https://github.com/yazzang-homelab/colab-fleet.git
cd colab-fleet
./install.sh              # creates a venv, installs the colab CLI + mcp

install.shが完了すると、残りの2つのステップが表示されます。

1) 自分のGoogleアカウントで一度認証する（ブラウザフローが開きます）

.venv/bin/colab sessions

トークンは~/.config/colab-cli/の下にのみ保存され、このツールを経由することはありません。

2) MCPクライアントに登録する

• Claude Code:

  claude mcp add -s user colab-fleet -- "$PWD/.venv/bin/python" "$PWD/server.py"

• pi / その他（mcpServers設定に追加）:

  "colab-fleet": { "command": "/abs/path/colab-fleet/.venv/bin/python", "args": ["/abs/path/colab-fleet/server.py"] }

確認：エージェントからgpu_doctor()を呼び出し、認証✅が表示されれば完了です。

3) ⭐（任意） インストール後、install.sh（または、見逃した場合は最初のツール呼び出し（gpu_doctor/gpu_submit））がスターを一度だけ要求します。エージェントはそのメッセージを中継するだけで、あなたがスターを押します。ツールがあなたの代わりにgh repo starを実行することはありません（つまり、あなたのGitHubアカウントには触れません）。

gh repo star yazzang-homelab/colab-fleet   # or hit ⭐ on the repo page

これによって機能が制限されることはありません。メッセージを完全に無効にするには、COLAB_FLEET_NO_STAR=1を設定してください。

要件：Python 3.10+、git。ローカルのGPUや重いライブラリは不要です。すべてColab上で実行されます。

使用方法

# 0) health check
gpu_doctor()

# 1) round-trip smoke test (no deps → ephemeral run)
gpu_submit(".../examples/selftest.py", accel="cpu", outputs="/content/selftest.json")
gpu_status(<id>); gpu_logs(<id>); gpu_fetch(<id>)

# 2) parallel hyperparameter sweep (deps + outputs → managed run)
gpu_submit(".../examples/sklearn_gridsearch.py", accel="cpu",
           deps="scikit-learn joblib", args="--folds 5",
           outputs="/content/result.json", timeout=1200)

# 3) train on your own CSV (inputs + deps + outputs → managed run)
gpu_submit(".../examples/train_on_csv.py", accel="cpu",
           deps="scikit-learn pandas joblib",
           inputs="/path/to/data.csv", args="--csv /content/data.csv",
           outputs="/content/model.pkl,/content/metrics.json", timeout=1800)

# real DL that needs a GPU (T4):
gpu_submit(".../my_torch_train.py", accel="t4", deps="torch ...", outputs="...")

成果物は~/.colab-fleet/jobs/job-<id>/に保存されます（環境変数で設定可能）。

ツール

ガードレール

• 無料枠ロック：accel ∈ {cpu, t4}のみ許可。A100/H100/L4/TPUはハード拒否されます（colabq.accel_flags）。そのため、有料のコンピュートユニット消費は構造的にゼロです。また、認識されないGPU名が静かにA100にフォールバックするCLIの落とし穴も無効化します。

• 自動ティアダウン：すべてのジョブはtry/finallyでcolab stopを実行します。ディスパッチャーはシャットダウン時に孤立したセッションも回収します。

• 直列キュー：無料枠では1セッションしか許可されないため、ジョブはflockで直列化され、同時送信はキューに並びます。

• 認証情報・個人情報の漏洩なし：ツール出力にはトークンやメールアドレスは含まれません。

チェックポイント再開（長時間ジョブ）

スクリプトが定期的にckptパスに保存し、起動時にそれを読み込む場合、ディスパッチャーはセッションが12時間/90分の上限に達したときに最後のチェックポイントを保持し、再試行時に再アップロードします。これにより、ジョブは複数のセッションにまたがって完了します。retriesで再試行回数を設定してください。

環境変数（任意）

COLAB_FLEET_AUTH（oauth2/adc）・COLAB_FLEET_TIMEOUT・COLAB_FLEET_ARTIFACTS（成果物の場所）・COLAB_FLEET_CONFIG・COLAB_FLEET_DB・COLAB_FLEET_BIN（colabバイナリのパスを強制）・COLAB_FLEET_NO_STAR（=1で一度きりのスター通知を無効化）・COLAB_FLEET_STAR_MARKER（メッセージが表示されたかどうかを記録するファイル。デフォルトは~/.config/colab-fleet/star-nudged）。

トラブルシューティング

注記

• Google Colabの無料ランタイムにはフェアユースポリシーがあります。このツールは回避行為（マルチアカウントのローテーション、キープアライブボットなど）を行いません。通常のジョブオフロードとクリーンアップのみです。

• 無料のCPUランタイムは約2 vCPUです。本当の利点はクリーンなRAMと開発マシンからの分離であり、コア数ではありません。実際のGPUアクセラレーションが必要な場合は、accel="t4"を使用してください。

ライセンス

MIT。駆動するエンジンであるgoogle-colab-cliはApache-2.0です（別ライセンス）。