colab-fleet

Descarga trabajo pesado de CPU/ML a Google Colab gratuito desde Claude Code (o cualquier cliente MCP) — con bloqueo de nivel gratuito, auto-destrucción, cola de trabajos y reanudación de puntos de control.

Inglés · 한국어

Ejecuta lo costoso — entrenamiento de ML, barridos de hiperparámetros, backtests — en un runtime gratuito de Google Colab en lugar de tu propia máquina, y recupera solo los artefactos. Un cliente MCP (Claude Code, pi, …) envía un trabajo con una sola llamada de herramienta (gpu_submit(...)) y los resultados se obtienen automáticamente cuando termina.

No necesitas GPU ni librerías pesadas localmente. Una cuenta gratuita de Colab es suficiente.

¿En qué se diferencia del CLI oficial colab?

En una línea: el CLI colab de Google es una herramienta que escribe un humano; colab-fleet es una herramienta que llama una IA. Mismo motor (el CLI oficial), con salvaguardas y automatización añadidas encima.

Google no incluyó un servidor MCP — solo un CLI de línea de comandos. Este proyecto lo envuelve para que un agente pueda manejarlo directamente.

Analogía: el CLI oficial es una transmisión manual; colab-fleet es automático + cinturón de seguridad + navegación sobre el mismo motor (el runtime gratuito de Colab).

Related MCP server: mcp-colab-gpu

Instalación (3 pasos)

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

Cuando install.sh termina, imprime los dos pasos restantes:

1) Autentícate una vez con tu propia cuenta de Google (abre un flujo de navegador)

.venv/bin/colab sessions

Los tokens se almacenan solo en ~/.config/colab-cli/ y nunca pasan por esta herramienta.

2) Regístrate con tu cliente MCP

• Claude Code:

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

• pi / otros (añade a tu configuración mcpServers):

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

Compruébalo: llama a gpu_doctor() desde el agente — auth ✅ significa que has terminado.

3) ⭐ (opcional) Después de la instalación, install.sh — o, si lo perdiste, la primera llamada de herramienta (gpu_doctor/gpu_submit) — pide una estrella exactamente una vez. El agente solo transmite ese mensaje; tú presionas la estrella. La herramienta nunca ejecuta gh repo star en tu nombre (es decir, no toca tu cuenta de GitHub).

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

Nada está bloqueado detrás de eso. Para silenciar el mensaje por completo, establece COLAB_FLEET_NO_STAR=1.

Requisitos: Python 3.10+, git. Una GPU local y librerías pesadas no son necesarias — todo se ejecuta en Colab.

Uso

# 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="...")

Los artefactos se guardan en ~/.colab-fleet/jobs/job-<id>/ (configurable mediante variable de entorno).

Herramientas

Salvaguardas

• Bloqueo de nivel gratuito: solo accel ∈ {cpu, t4}. A100/H100/L4/TPU son rechazados de forma estricta (colabq.accel_flags), por lo que el gasto en unidades de cómputo de pago es estructuralmente cero. Esto también desactiva la trampa del CLI donde un nombre de GPU no reconocido cae silenciosamente a A100.

• Auto-destrucción: cada trabajo ejecuta colab stop en un try/finally. El despachador también elimina sesiones huérfanas al apagarse.

• Cola serial: el nivel gratuito permite una sesión, por lo que los trabajos se serializan con flock; los envíos concurrentes se ponen en cola.

• Sin fuga de credenciales/PII: la salida de la herramienta no contiene tokens ni direcciones de correo.

Reanudación de puntos de control (trabajos largos)

Si tu script guarda periódicamente en la ruta ckpt y la carga al inicio, el despachador conserva el último punto de control cuando una sesión alcanza el límite de 12h/90min y lo vuelve a subir en el reintento — así un trabajo termina a través de múltiples sesiones. Usa retries para establecer el número de reintentos.

Variables de entorno (opcional)

COLAB_FLEET_AUTH (oauth2/adc) · COLAB_FLEET_TIMEOUT · COLAB_FLEET_ARTIFACTS (ubicación de artefactos) · COLAB_FLEET_CONFIG · COLAB_FLEET_DB · COLAB_FLEET_BIN (forzar la ruta del binario colab) · COLAB_FLEET_NO_STAR (=1 desactiva el mensaje de estrella único) · COLAB_FLEET_STAR_MARKER (archivo que registra si se mostró el mensaje; por defecto ~/.config/colab-fleet/star-nudged).

Solución de problemas

Notas

• El runtime gratuito de Google Colab tiene una política de uso justo. Esta herramienta no realiza ninguna evasión (sin rotación de múltiples cuentas, sin bots de mantenimiento) — solo descarga de trabajos ordinaria y limpieza.

• El runtime de CPU gratuito tiene aproximadamente 2 vCPUs; la verdadera ventaja es RAM limpia y aislamiento de tu máquina de desarrollo, no el número de núcleos. Si necesitas aceleración GPU real, usa accel="t4".

Licencia

MIT. El motor que maneja, google-colab-cli, es Apache-2.0 (separado).