Mighty-Colab: A Mightier Interface for Colab

A command-line interface for Google Colab with quality-of-life improvements for humans and AI agents. Provision high-performance CPU, GPU, and TPU runtimes, execute local code, manage remote files, and orchestrate automated cloud pipelines — directly from your terminal, or via embedded MCP server.

Designed to support seamless developer productivity, headless automation, and AI agent integrations. This CLI can co-exist with the official colab CLI.

Demo

[!NOTE] Platform support: the Colab CLI currently supports Linux and macOS only. Windows is not supported at this time.

[!TIP] Looking for in-notebook, interactive agent-assisted coding instead of a terminal workflow? See the Official Colab MCP Server.

[!TIP] This project embeds an MCP Server wrapper around automation-friendly CLI commands.

[!NOTE] What problem does this project solve?

1. mighty-colab adopt ENDPOINT brings a Colab runtime that was started outside the CLI (e.g. from the Colab web UI) under local session tracking, so stop/status/exec etc. can manage it.
2. mighty-colab adopt --orphanage does the same for every such orphaned runtime at once.
3. Embeds an MCP server (mighty-colab mcp) so AI agents can call these commands as tools directly, without shelling out.

Key Features

• Instant VM Provisioning: Spin up CPU, GPU (T4, L4, G4, H100, A100), or TPU (v5e1, v6e1) runtimes in seconds.
• Robust Code Execution: Run local Python scripts, Jupyter Notebooks (.ipynb), or piped stdin code; launch interactive REPLs or raw TTY console shells.
• Ephemeral Job Runner (mighty-colab run): Provision a fresh VM, execute a local script with forwarded arguments, retrieve output files, and automatically tear down the runtime in a single command.
• Automatic Keep-Alive: Built-in background daemon automatically prevents idle VM termination, keeping resource allocations active without requiring open browser tabs.
• Seamless Workspace Automation: Mount Google Drive, authenticate Google Cloud Platform (GCP) credentials, and install dependencies with high-performance uv package management.
• State & Log Archival: Inspect local session states or export interactive history logs to standard Jupyter Notebooks, Markdown, or structured JSONL.
• Orphan Recovery (mighty-colab adopt): Bring a Colab runtime started outside the CLI (e.g. from the web UI) under local session tracking, one at a time or all at once with --orphanage.
• Embedded MCP Server (mighty-colab mcp): Expose the CLI's own commands as MCP tools over stdio, so AI agents can call them directly instead of shelling out.

Installation

mighty-colab is published on PyPI. Install it using uv (recommended) or standard pip:

# Using uv (recommended)
uv tool install mighty-colab
# Using pip
pip install mighty-colab

Quick Start

Run a CPU-based VM runtime, execute some code, and clean up:

# 1. Provision a new session
mighty-colab new

# 2. Execute code from stdin
echo "print('Hello from Google Colab!')" | mighty-colab exec

# 3. Stop and release the VM resource
mighty-colab stop

[!NOTE] When only one session is active, you can omit the -s, --session option; the CLI automatically knows it.

MCP Server Configuration

mighty-colab embeds an MCP (Model Context Protocol) server, exposing its commands as tools for AI agents like Claude. Since the package is on PyPI, uvx can run it directly without a separate install step:

{
  "mcpServers": {
    "mighty-colab": {
      "command": "uvx",
      "args": [
        "mighty-colab",
        "mcp"
      ],
      "env": {
        "UV_WORKING_DIR": "/Optional/Path/To/Working_Dir"
      }
    }
  }
}

See MCP Server Design for which commands are exposed as tools and how global flags (--auth, --config) can be added to args.

Command Index

Run mighty-colab <command> --help to view specific options, defaults, and detailed help.

Session Management

Execution

File Operations

Automation & Utilities

Global Options

• --auth {oauth2,adc} — Authentication strategy for the Colab API (default: adc).
• -c, --client-oauth-config PATH — Path to public OAuth client credentials configuration (default: ~/.colab-cli-oauth-config.json).
• --config PATH — Path to local session metadata storage (default: ~/.config/colab-cli/sessions.json).
• --logtostderr — Direct debug logging output to stderr.

Practical Examples

Accelerator Training with Checkpoint Retrieval

Provision an A100 GPU, install requirements, run a local training script, retrieve the resulting model weights, and terminate the VM:

mighty-colab new -s trainer --gpu A100
mighty-colab install -s trainer torch transformers
mighty-colab exec -s trainer -f train.py
mighty-colab download -s trainer checkpoints/model.bin ./model.bin
mighty-colab stop -s trainer

Workspace Notebook Execution with Drive Integration

Mount Google Drive, run a local notebook against the VM kernel (outputs are written back into report_output.ipynb), export a Markdown log of the execution, and clean up:

mighty-colab new -s analysis
mighty-colab drivemount -s analysis
mighty-colab exec -s analysis -f report.ipynb
mighty-colab log -s analysis -o execution_log.md
mighty-colab stop -s analysis

Usage Notes

• TTY Requirements: The interactive commands repl and console require a local TTY. When running inside automated scripts or pipelines, make sure to pipe stdin (e.g., echo "print(1)" | mighty-colab repl) to trigger non-interactive execution modes.
• Transparent Code Execution: When calling mighty-colab exec -f file.py, the CLI reads the file locally and transmits its content to the remote kernel. You do not need to manually upload files before execution.
• Storage & State Paths: Session tokens and metadata are stored at ~/.config/colab-cli/sessions.json. Global CLI settings are located at ~/.config/colab-cli/settings.json. These can be customized or isolated via the global --config flag.

Ephemeral Accelerator Jobs

Use mighty-colab run to run a local script on dedicated hardware without manual session lifecycle management. The CLI handles provisioning, script execution, and immediate VM teardown automatically:

# Run train.py on a T4 GPU and release the VM on completion
mighty-colab run --gpu T4 train.py

Shebang Execution Support

To execute a local file directly on a remote accelerator, place the mighty-colab run interpreter in the shebang line:

#!/usr/bin/env -S mighty-colab run --gpu L4 --keep
import torch

print("L4 GPU Available:", torch.cuda.is_available())
print("Device Name:", torch.cuda.get_device_name(0))

Make the script executable (chmod +x script.py) and run it: ./script.py. The --keep option tells the CLI to preserve the session VM on completion so you can re-execute or inspect logs.

Deep Dive Documentation

For comprehensive architectural overviews and deep-dives into specific CLI sub-systems, refer to the detailed documentation:

• Session Management & Keep-Alive Architecture
• Interactive & Non-Interactive Execution Design
• File Management & Jupyter Contents API
• Authentication Providers & VM Automation
• Ephemeral Job Runner Design
• SSH-over-WebSocket Runtime Access
• MCP Server Design

To view interactive walkthroughs of eleven real-world automated scenarios, check out the Demo Walkthroughs.

Contributing

Feedback and contributions are welcome! Please read CONTRIBUTING.md for details.