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

!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