colabctl
An async SDK, CLI and MCP server for running code on Google Colab without the website — allocate runtimes, run scripts and notebooks, stream output, move files. Its job API spans seven backends, with price-ordered routing, failover on infrastructure errors, and detached jobs that relaunch when Colab reclaims a runtime.
$ pip install "colabctl[cli,sdk]"Python 3.12 · asyncio · Typer · Pydantic · MCP · PyPI
0.5.0 on PyPI · Apache-2.0 · Colab and Modal verified against real accounts
- 716
- hermetic test functions
- 7
- backends behind one job API
- 19
- MCP tools
Two shapes of compute
A TransportAdapter is a warm interactive runtime: allocate, execute, transfer files, release. A Backend is a batch job: submit, status, logs, result, cancel. Colab implements both.
Colab has three transports. The default is Google's official CLI; an opt-in native transport adds cross-process attach, streaming kernel output, keep-alive and file transfer; the third drives a logged-in browser tab.
Python SDK · CLI · MCP server
│
┌──────────────┴───────────────┐
TransportAdapter Backend
interactive runtimes batch jobs
│ │
cli · native · browser colab · modal · vertex · hf
kaggle · runpod · vast
│
BackendRouter
price catalog · failover
auth · secrets · state · cost · audit · observability Python SDK · CLI · MCP server
│
┌──────────────┴───────────────┐
TransportAdapter Backend
interactive runtimes batch jobs
│ │
cli · native · browser colab · modal · vertex · hf
kaggle · runpod · vast
│
BackendRouter
price catalog · failover
auth · secrets · state · cost · audit · observabilityRouting and failover
BackendRouter filters backends by accelerator, optionally ranks them by a price catalog, and caps the hourly price. The catalog chains live feeds and always falls back to a static in-repo table.
Only infrastructure errors — allocation, quota, transport — trigger failover. A job whose own code failed isn't re-run somewhere else, and because fallback re-executes the work, it's limited to jobs marked idempotent.
Detached, resumable jobs
The detached Colab backend starts the workload as a supervised OS process on the runtime and stores a job record in a lock-guarded state file, so any later process can check status, tail logs or cancel.
With --resumable, a status poll that finds the runtime reclaimed allocates a new one and relaunches the stored job as a new incarnation. Checkpointing to external storage stays the workload's job.
Built for agents — and honest about coverage
colabctl-mcp exposes runtime, batch and detached-job tools. Every error carries a stable code and a remediation hint, and the wheel ships an agent skill (colabctl skill install).
Only Colab and Modal have been exercised against real accounts. Vertex AI, Hugging Face Jobs, Kaggle, RunPod and Vast.ai are implemented and covered by hermetic tests, and the README says exactly that.