colab-fleet

Разгрузите тяжёлую CPU/ML работу на бесплатный Google Colab из Claude Code (или любого MCP-клиента) — с блокировкой бесплатного тарифа, автоматическим завершением, очередью заданий и возобновлением с контрольных точек.

English · 한국어

Запускайте дорогостоящие задачи — обучение ML, перебор гиперпараметров, бэктесты — на бесплатном рантайме Google Colab вместо своей машины и забирайте только артефакты. MCP-клиент (Claude Code, pi, …) отправляет задание одним вызовом инструмента (gpu_submit(...)), и результаты автоматически подтягиваются по завершении.

Вам не нужен GPU и тяжёлые библиотеки локально. Достаточно бесплатного аккаунта Colab.

Чем это отличается от официального CLI colab?

Одна строка: официальный CLI colab — это инструмент, в который печатает человек; colab-fleet — инструмент, который вызывает ИИ. Тот же движок (официальный 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 / others (добавьте в конфиг 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), поэтому расход платных вычислительных единиц структурно равен нулю. Это также обезвреживает ловушку CLI, где нераспознанное имя GPU молча откатывается к A100.

• Автоматическое завершение: каждое задание выполняет colab stop в try/finally. Диспетчер также удаляет осиротевшие сессии при завершении.

• Последовательная очередь: бесплатный тариф допускает одну сессию, поэтому задания сериализуются с помощью flock; одновременные отправки встают в очередь.

• Нет утечки учётных данных/персональных данных: вывод инструмента не содержит токенов или email-адресов.

Возобновление с контрольной точки (долгие задания)

Если ваш скрипт периодически сохраняет данные в путь 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 (отдельно).