claude-colab

claude-colab

Give Claude Code GPU access via Google Colab.

AI coding agents can read files, run bash, and edit code — but they have zero GPU access. claude-colab bridges that gap using Colab's free T4 GPU.

How It Works

Colab (T4 GPU)                              Your Mac / PC
┌─────────────────────────┐                 ┌──────────────────────┐
│ Flask API               │                 │ claude-colab CLI     │
│  /exec, /python,        │◄── HTTPS ──────►│  or                  │
│  /upload, /download     │  (cloudflared)  │ MCP Server           │
│                         │  E2E encrypted  │  (Claude Code tools) │
│ Bearer token + Fernet   │                 │                      │
└─────────────────────────┘                 └──────────────────────┘

1. Open one Colab notebook, hit "Run All"
2. Copy the connection string
3. Claude Code gains GPU access

Quick Start

Install

pip install claude-colab

Start the Colab server

Open notebooks/claude_colab_server.ipynb in Google Colab. Set runtime to T4 GPU. Run all cells. Copy the connection string.

Connect

claude-colab connect cc://TOKEN:KEY@your-tunnel.trycloudflare.com

Use it

claude-colab status                          # GPU info
claude-colab exec "nvidia-smi"               # Run shell commands
claude-colab python -c "import torch; print(torch.cuda.get_device_name(0))"
claude-colab upload model.py /content/model.py
claude-colab download /content/results.csv ./results.csv

MCP Server (Claude Code Integration)

Add to ~/.claude/settings.json:

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

Claude Code now has 5 GPU tools:

| Tool | What it does | |------|-------------| | colab_status | GPU info, VRAM, disk, uptime | | colab_exec | Run shell commands | | colab_python | Execute Python code | | colab_upload | Upload files to Colab | | colab_download | Download files from Colab |

Example

You: "Benchmark this model on the GPU"

Claude:
1. colab_status → Tesla T4, 15GB VRAM
2. colab_upload → sends model.py
3. colab_exec → "pip install torch transformers"
4. colab_exec → "python model.py"
5. colab_download → fetches results.json

Connection Safety

The connection string contains your auth token and encryption key. Three ways to connect:

# Direct (convenient, visible in shell history)
claude-colab connect cc://TOKEN:KEY@host

# Interactive prompt (nothing in history)
claude-colab connect

# Pipe from clipboard (nothing in ps aux or history)
pbpaste | claude-colab connect -

Security

E2E Encryption

All request and response bodies are encrypted with Fernet (AES-128-CBC + HMAC-SHA256). The encryption key is generated per Colab session and is separate from the bearer token.

| Actor | Can see | Cannot see | |-------|---------|------------| | Random user | Nothing (no token) | Everything | | Cloudflare | URL paths, timing, token | Request/response bodies | | Google (Colab) | Everything on the VM | Your local files |

What we don't protect against

• Google seeing data on the Colab VM — it's their hardware
• Arbitrary code execution on Colab — intentional, it's your session
• Local machine compromise exposing ~/.claude-colab.json

Limitations

• Session timeout: Free Colab dies after 90min idle / 12hr max. You'll need to restart and reconnect.
• No streaming: Long-running commands return nothing until completion. Redirect to file: colab_exec "python train.py > output.log 2>&1"
• 50MB file limit: For larger files, use colab_exec with wget or gdown.
• No persistent state: Each /python call runs in a fresh namespace.

License

MIT