Content
# Tool List
> Offload heavy CPU/ML work to **free Google Colab** from Claude Code (or any MCP client) — with a free-tier lock, auto-teardown, a job queue, and checkpoint-resume.
## Overview
This tool allows you to offload heavy CPU/ML work to free Google Colab from Claude Code or any MCP client, with features such as free-tier lock, auto-teardown, job queue, and checkpoint-resume.
## Key Features
* Offload heavy CPU/ML work to free Google Colab
* Free-tier lock for cost-effective usage
* Auto-teardown for automatic session termination
* Job queue for managing concurrent jobs
* Checkpoint-resume for resuming interrupted jobs
## Comparison with Official `colab` CLI
| Category | Official `colab` CLI | colab-fleet (this wrapper) |
| --- | --- | --- |
| **Usage** | Directly by humans in terminal | Called by AI with `gpu_submit(...)` |
| **Cost prevention** | No restriction on accelerators | Only free (cpu/t4) allowed, reject paid hardware |
| **Timeout** | Default 30 seconds, may interrupt ML jobs | Longer timeout (1 hour by default) with checkpointing |
| **Session management** | Manual session management | Automatic session termination and orphan session cleanup |
| **Concurrent execution** | No protection, may cause conflicts | Jobs are queued and executed one by one |
| **Data transfer** | Manual upload/download | Automatic upload, execution, and output retrieval |
## Installation
```bash
git clone https://github.com/yazzang-homelab/colab-fleet.git
cd colab-fleet
./install.sh # Create venv and install colab CLI and mcp
```
After installation, follow the instructions to:
1. Authenticate with your Google account (browser flow will open)
```bash
.venv/bin/colab sessions
```
Tokens are stored in `~/.config/colab-cli/` and **not passed through this tool**.
2. Register with MCP client:
* Claude Code:
```bash
claude mcp add -s user colab-fleet -- "$PWD/.venv/bin/python" "$PWD/server.py"
```
* pi / other (add to mcpServers configuration):
```json
"colab-fleet": { "command": "/abs/path/colab-fleet/.venv/bin/python", "args": ["/abs/path/colab-fleet/server.py"] }
```
## Usage
```python
# 0) Health check
gpu_doctor()
# 1) Round-trip verification (0 dependencies → 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)
gpu_submit(".../examples/sklearn_gridsearch.py", accel="cpu",
deps="scikit-learn joblib", args="--folds 5",
outputs="/content/result.json", timeout=1200)
# 3) Upload CSV and train (inputs + deps + outputs → managed)
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)
# For real DL with GPU (T4) acceleration:
gpu_submit(".../my_torch_train.py", accel="t4", deps="torch ...", outputs="...")
```
Outputs are downloaded to `~/.colab-fleet/jobs/job-<id>/` (configurable via environment variables).
### Tool List
| Tool | Description |
| --- | --- |
| `gpu_submit(script, accel, deps, args, inputs, outputs, ckpt, timeout, retries, label)` | Submit job (asynchronous), return job ID |
| `gpu_status(job_id=0)` | Get job details / recent job + active sessions if 0 |
| `gpu_logs(job_id, lines)` | Tail job logs |
| `gpu_fetch(job_id)` | List output files |
| `gpu_sessions()` | List active Colab sessions |
| `gpu_stop(name="all")` | Stop sessions (protect units) |
| `gpu_doctor()` | Health, authentication, and queue status |
## Guardrails
* **Free-tier lock**: Only `accel ∈ {cpu, t4}` allowed. A100/H100/L4/TPU **rejected** (`colabq.accel_flags`) → structurally zero compute unit (paid) billing.
* **Auto-teardown**: All jobs are `colab stop`ped in try/finally block. Dispatcher also reclaims orphan sessions on exit.
* **Serial queue**: Free tier has 1 session → use `flock` to serialize, queue concurrent submissions.
* **Credential/PII non-exposure**: Tool output **never contains** tokens or emails.
## Checkpoint-Resume (long-running jobs)
If script periodically saves to `ckpt` path and loads/resumes from it, dispatcher will keep last checkpoint and retry from it if session gets terminated (e.g., 12h/90min cap), allowing **job completion across multiple sessions**. Use `retries` to specify retry count.
## Environment Variables (optional)
`COLAB_FLEET_AUTH`(oauth2/adc) · `COLAB_FLEET_TIMEOUT` · `COLAB_FLEET_ARTIFACTS`(output location) · `COLAB_FLEET_CONFIG` · `COLAB_FLEET_DB` · `COLAB_FLEET_BIN`(force colab path).
## Troubleshooting
| Symptom | Cause/Action |
| --- | --- |
| `gpu_doctor` authentication ❌ | Incomplete login → authenticate with `.venv/bin/colab sessions` |
| 401/403 | Insufficient scope → re-login (or `COLAB_FLEET_AUTH=adc` + `gcloud auth application-default login`) |
| GPU not allocated (400 on new) | Free T4 availability varies → fallback to `accel="cpu"` |
| Job stuck in queued | Dispatcher not running → manually run `.venv/bin/python dispatch.py` |
| Upload 500/failure | `colab upload`=Jupyter API **limits input >80MB**. Reduce size or compress. Dispatcher marks upload failure as job failure (no concealment) |
| Done but no result | Remote script exception → sentinel not output → treat as failure. Check stderr traceback with `gpu_logs` |
## Note
* Google Colab free runtime has **fair usage policies**. This tool does not bypass these policies and only offloads jobs within normal ranges.
* Free CPU runtime is approximately 2 vCPU — **clean RAM and isolation from dev PC** are more valuable than core count. If real GPU acceleration is needed, use `accel="t4"`.
## License
MIT. The engine [`google-colab-cli`](https://pypi.org/project/google-colab-cli/) is Apache-2.0 (separate).
