colab-fleet

Lagere schwere CPU/ML-Arbeit an kostenloses Google Colab von Claude Code (oder einem beliebigen MCP-Client) aus — mit Free-Tier-Sperre, automatischem Teardown, einer Job-Warteschlange und Checkpoint-Resume.

English · 한국어

Führe das Teure aus — ML-Training, Hyperparameter-Suchen, Backtests — auf einer kostenlosen Google-Colab-Laufzeitumgebung statt auf deiner eigenen Maschine aus und hole nur die Artefakte zurück. Ein MCP-Client (Claude Code, pi, …) reicht einen Job mit einem einzigen Tool-Aufruf ein (gpu_submit(...)) und die Ergebnisse werden automatisch abgerufen, wenn er fertig ist.

Du brauchst lokal keine GPU und keine schweren Bibliotheken. Ein kostenloses Colab-Konto reicht aus.

Wie unterscheidet sich das von der offiziellen colab-CLI?

Ein Satz: Die colab-CLI von Google ist ein Werkzeug, das ein Mensch eintippt; colab-fleet ist ein Werkzeug, das eine KI aufruft. Gleiche Engine (die offizielle CLI), mit Schutzmechanismen und Automatisierung obendrauf.

Google hat keinen MCP-Server ausgeliefert — nur eine Kommandozeilen-CLI. Dieses Projekt umhüllt sie, damit ein Agent sie direkt steuern kann.

Analogie: Die offizielle CLI ist ein Schaltgetriebe; colab-fleet ist Automatik + Sicherheitsgurt + Navigation auf derselben Engine (der kostenlosen Colab-Laufzeitumgebung).

Related MCP server: mcp-colab-gpu

Installation (3 Schritte)

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

Wenn install.sh fertig ist, zeigt es die verbleibenden zwei Schritte an:

1) Authentifiziere dich einmal mit deinem eigenen Google-Konto (öffnet einen Browser-Ablauf)

.venv/bin/colab sessions

Tokens werden nur unter ~/.config/colab-cli/ gespeichert und fließen nie durch dieses Tool.

2) Registriere dich bei deinem MCP-Client

• Claude Code:

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

• pi / andere (füge es zu deiner mcpServers-Konfiguration hinzu):

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

Prüfe es: Rufe gpu_doctor() vom Agenten auf — Auth ✅ bedeutet, du bist fertig.

3) ⭐ (optional) Nach der Installation bittet install.sh — oder, falls du es verpasst hast, der erste Tool-Aufruf (gpu_doctor/gpu_submit) — genau einmal um einen Stern. Der Agent leitet nur diese Nachricht weiter; du drückst den Stern. Das Tool führt niemals gh repo star in deinem Namen aus (d. h. es berührt dein GitHub-Konto nicht).

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

Nichts ist dahinter versteckt. Um die Nachricht vollständig zu deaktivieren, setze COLAB_FLEET_NO_STAR=1.

Voraussetzungen: Python 3.10+, git. Eine lokale GPU und schwere Bibliotheken sind nicht nötig — alles läuft auf Colab.

Verwendung

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

Artefakte landen in ~/.colab-fleet/jobs/job-<id>/ (per Umgebungsvariable konfigurierbar).

Tools

Schutzmechanismen

• Free-Tier-Sperre: nur accel ∈ {cpu, t4}. A100/H100/L4/TPU werden hart abgelehnt (colabq.accel_flags), sodass kostenpflichtige Compute-Unit-Ausgaben strukturell null sind. Das entschärft auch die CLI-Falle, bei der ein nicht erkannter GPU-Name stillschweigend auf A100 zurückfällt.

• Auto-Teardown: Jeder Job führt colab stop in einem try/finally aus. Der Dispatcher räumt beim Herunterfahren auch verwaiste Sessions ab.

• Serielle Warteschlange: Das Free-Tier erlaubt eine Session, daher werden Jobs mit flock serialisiert; gleichzeitige Einreichungen stellen sich in die Warteschlange.

• Kein Leck von Zugangsdaten/PII: Die Tool-Ausgabe enthält keine Tokens oder E-Mail-Adressen.

Checkpoint-Resume (lange Jobs)

Wenn dein Skript regelmäßig in den ckpt-Pfad speichert und es beim Start lädt, behält der Dispatcher den letzten Checkpoint, wenn eine Session das 12h/90min-Limit erreicht, und lädt ihn beim erneuten Versuch wieder hoch — so wird ein Job über mehrere Sessions hinweg abgeschlossen. Verwende retries, um die Anzahl der Wiederholungsversuche festzulegen.

Umgebungsvariablen (optional)

COLAB_FLEET_AUTH (oauth2/adc) · COLAB_FLEET_TIMEOUT · COLAB_FLEET_ARTIFACTS (Artefakt-Speicherort) · COLAB_FLEET_CONFIG · COLAB_FLEET_DB · COLAB_FLEET_BIN (erzwingt den colab-Binärpfad) · COLAB_FLEET_NO_STAR (=1 deaktiviert die einmalige Stern-Nachricht) · COLAB_FLEET_STAR_MARKER (Datei, die aufzeichnet, ob die Nachricht angezeigt wurde; Standard ~/.config/colab-fleet/star-nudged).

Fehlerbehebung

Hinweise

• Die kostenlose Laufzeitumgebung von Google Colab hat eine Fair-Use-Richtlinie. Dieses Tool führt keine Umgehung durch (keine Multi-Account-Rotation, keine Keep-Alive-Bots) — nur gewöhnliches Job-Offloading und Aufräumen.

• Die kostenlose CPU-Laufzeitumgebung hat ungefähr 2 vCPUs; der eigentliche Gewinn ist sauberer RAM und Isolation von deiner Entwicklungsmaschine, nicht die Kernanzahl. Wenn du echte GPU-Beschleunigung brauchst, verwende accel="t4".

Lizenz

MIT. Die Engine, die es antreibt, google-colab-cli, ist Apache-2.0 (separat).