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 运行完成后会打印剩余两步：

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）——会恰好一次请求一个 star。工具只是转达这条消息；你来按 star。工具绝不会替你运行 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），因此付费计算单元支出在结构上为零。这也解除了 CLI 的一个隐患——无法识别的 GPU 名称会静默回退到 A100。

• 自动销毁：每个任务都在 try/finally 中运行 colab stop。调度器在关闭时也会回收孤儿会话。

• 串行队列：免费层只允许一个会话，因此任务通过 flock 串行化；并发提交会排队等待。

• 无凭据/PII 泄露：工具输出中不包含任何令牌或邮箱地址。

断点续跑（长任务）

如果你的脚本定期保存到 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 禁用一次性 star 消息）· COLAB_FLEET_STAR_MARKER（记录消息是否已显示的文件；默认 ~/.config/colab-fleet/star-nudged）。

故障排查

说明

• Google Colab 的免费运行时遵循合理使用政策。本工具不做任何规避（不轮换多账号、不跑保活机器人）——只是普通的任务卸载和清理。

• 免费 CPU 运行时大约 2 个 vCPU；真正的价值在于干净的内存和与开发机的隔离，而不是核心数。如果你需要真正的 GPU 加速，使用 accel="t4"。

许可证

MIT。它所驱动的引擎 google-colab-cli 是 Apache-2.0（独立项目）。