Colab Skill

Execute Python on Google Colab GPU runtimes via headless API. No browser needed.

Setup

1. Authenticate with Colab (one-time): Run the colab-mcp OAuth flow to create ~/.colab-mcp-auth-token.json. See https://github.com/googlecolab/colab-mcp
2. Add Drive scope (optional, for persistence): scripts/reauth_with_drive.py
3. Enable Drive API (if using Drive): https://console.developers.google.com/apis/api/drive.googleapis.com — enable for your GCP project
4. Python deps: On first run, colab_run.py auto-creates a .colab-venv/ venv via uv and installs deps. Requires uv (install: pip install uv). Deps: google-auth-oauthlib, google-auth, jupyter-kernel-client, requests, google-api-python-client

Scripts

All scripts live in scripts/ and use a .colab-venv/ sibling directory for dependencies.

colab_run.py — Execute code on Colab

# Inline code on CPU
python3 scripts/colab_run.py exec "print('hello')"

# Script on T4 GPU
python3 scripts/colab_run.py exec --gpu T4 --file script.py

# Keep runtime alive between calls
python3 scripts/colab_run.py exec --gpu T4 --keep "x = 42"

# GPU options: T4 (default), L4, A100, H100
python3 scripts/colab_run.py exec --gpu A100 --file heavy_training.py

# Runtime management
python3 scripts/colab_run.py list          # Active runtimes
python3 scripts/colab_run.py stop <ep>     # Stop runtime
python3 scripts/colab_run.py info          # CU balance + eligible GPUs

colab_drive.py — Google Drive file transfer

python3 scripts/colab_drive.py upload file.pt --folder colab-workspace
python3 scripts/colab_drive.py download checkpoint.pt --output ./checkpoint.pt
python3 scripts/colab_drive.py list --folder colab-workspace

Requires drive.file OAuth scope (run scripts/reauth_with_drive.py once).

inject_and_run.sh — Run scripts with Drive access inside Colab

Injects the local OAuth token into a script before sending it to Colab. Place __COLAB_TOKEN_PLACEHOLDER__ where the base64 token should go:

bash scripts/inject_and_run.sh my_script.py --gpu T4

Inside the script:

import json, base64
from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build

token_data = json.loads(base64.b64decode("__COLAB_TOKEN_PLACEHOLDER__"))
with open('/tmp/token.json', 'w') as f:
    json.dump(token_data, f)
creds = Credentials.from_authorized_user_file('/tmp/token.json')
service = build('drive', 'v3', credentials=creds)

colab_tts.py — Voice synthesis via F5-TTS

# One-time: fetch voice samples from ElevenLabs
python3 scripts/colab_tts.py fetch-voice --voice-id <id> --api-key <key>

# Generate speech with cloned voice
python3 scripts/colab_tts.py speak "Hello world" --output hello.wav --gpu T4

reauth_with_drive.py — Add Drive scope to OAuth token

python3 scripts/reauth_with_drive.py

Opens browser for Google sign-in. One-time setup.

GPU Selection Guide

Start with T4. Escalate only when VRAM or speed demands it.

Patterns

Short task (inference, TTS, quick experiment)

Assign → execute → get output → unassign. Don't use --keep.

Multi-step session

Use --keep. State persists in kernel between exec calls. Unassign when done.

Long training with Drive checkpoints

Use inject_and_run.sh. Script checkpoints to Drive every N epochs. If runtime dies, re-run — script loads latest checkpoint from Drive. See references/examples.md for template.

Structured output

Embed parseable markers in script stdout:

print(f"__RESULT__{json.dumps(metrics)}")    # Structured data
print(f"__AUDIO__{base64_audio}")             # Binary as base64

Timeouts

• Idle timeout (Pro): ~90 min without active execution
• Max session (Pro): ~24 hours continuous
• Active code execution prevents idle disconnect
• Runtime death loses /tmp/ — use Drive for anything you need to keep

API Quirk

GPU assignment requires split GET/POST: GET fetches XSRF token (no GPU params), POST creates assignment with variant=GPU&accelerator=T4. Already handled by colab_run.py.