colab-autopilot

colab-autopilot

Give Claude Code (or any MCP-compatible AI agent) autonomous access to your Google Colab GPU — no browser tab needed after setup.

Built for long-running RL training workflows where you want the agent to monitor, detect issues, stop, debug, fix, and restart training while you're away.

How It Works

┌─────────────────┐     cloudflared tunnel (E2E encrypted)     ┌──────────────────┐
│  Your Machine   │ ──────── HTTPS ─────────────────────────► │  Google Colab     │
│                 │                                            │  (GPU Runtime)    │
│  Claude Code    │ ◄── compact metrics summary ────────────── │  Flask API        │
│  ↕ MCP Server   │ ──── kill job / write fix ────────────────► │  Job Manager      │
│                 │ ◄── job status ─────────────────────────── │  Training Loop    │
└─────────────────┘                                            └──────────────────┘

No browser tab needed after initial setup.
No Google Drive sync delays.
Sub-second round-trip communication.

Key Features

• No browser tab needed — Colab runs headless after you start the tunnel
• Token-safe — Training output never floods the agent's context. A /training_summary endpoint returns ~500 tokens with metrics digest + anomaly detection
• Background jobs — Submit training via /submit_job, monitor with /job_logs, kill with /kill_job
• Autonomous debug loop — Agent can: detect NaN/reward collapse → stop run → read code → write fix → restart
• E2E encrypted — Fernet AES-128 encryption. Cloudflare only sees ciphertext
• 12 MCP tools — Status, training summary, raw logs, exec, python, submit/kill/monitor jobs, file read/write, upload/download, checkpoints

Setup

1. Install locally (one time)

pip install git+https://github.com/Emile-Andre/colab-autopilot.git

2. Add to Claude Code config

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "colab-autopilot": {
      "command": "colab-autopilot",
      "args": ["mcp-serve"]
    }
  }
}

3. Set up Colab (each new session)

Copy the 3 setup cells from notebooks/autopilot_setup.ipynb into the TOP of your Colab notebook, before any model code. Or just paste them manually:

Cell 1: Install deps ``python !pip install -q flask cryptography !wget -q https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -O /usr/local/bin/cloudflared 2>/dev/null !chmod +x /usr/local/bin/cloudflared ``

Cell 2: Start server (see notebooks/colab_autopilot_server.py)

Cell 3: Open tunnel — prints the cc://... connection string

4. Connect (each new session)

colab-autopilot connect cc://TOKEN:KEY@host

5. Close the browser tab

Your Colab runtime keeps running. Claude Code now has full GPU access.

Configuration

Edit these variables in the Cell 2 server code to match your notebook:

TRAINING_LOG_PATH = "/content/drive/MyDrive/world_model/training_logs.jsonl"
CHECKPOINT_DIR = "/content/drive/MyDrive/world_model/weights"
WORK_DIR = "/content"

Token Budget

The system is designed to keep agent context usage minimal:

| Operation | ~Tokens | |-----------|---------| | colab_training_summary | 300-500 | | colab_job_logs(n_lines=20) | 200-400 | | colab_status | 100-200 | | colab_exec (small output) | 200-500 | | Full training stdout (raw) | 50,000+ ❌ |

The summary endpoint does the heavy lifting server-side: it reads your JSONL logs, computes rolling averages, samples the loss curve to 10 points, and runs anomaly detection — all before sending anything to the agent.

Compared to ColabWatcher4aiAgents

| Feature | ColabWatcher | colab-autopilot | |---------|-------------|-----------------| | Transport | Google Drive sync | Cloudflare tunnel (HTTPS) | | Latency | 15-60+ seconds | Sub-second | | Browser needed | No (Drive-based) | No (tunnel-based) | | Real-time logs | No (file-based) | Yes (ring buffer) | | Token management | No | Yes (summary endpoint) | | Background jobs | Sequential queue | Parallel with kill/monitor | | Anomaly detection | No | Yes (NaN, collapse, stagnation) | | File editing | Via Drive | Direct API | | Encryption | No | Fernet E2E |

License

MIT