Mighty Colab

Google Colab runtimes your coding agent can operate without babysitting.

mighty-colab is a compatibility-first fork of Google's official colab CLI, hardened for AI agents that provision runtimes, execute code, wait for long jobs, recover state, and tear everything down without a human watching the terminal.

It installs as a separate binary, so mighty-colab and colab can coexist. The upstream commands and flags remain familiar; this fork adds the machine-readable contracts and failure handling that unattended workflows need.

Watch the demo · Read the agent field notes · Open the operator skill

[!NOTE] Linux and macOS only. Python 3.12 or newer is required.

Why Mighty Colab?

A human has peripheral vision. An agent has exit codes, stdout, and a tool-call deadline.

Mighty Colab was shaped by a multi-month, agent-driven ML research pipeline: real A100 sessions, hour-long jobs, artifacts written to GCS, and real billing. That work exposed failure modes a person at a terminal can often notice and correct, but an unattended agent cannot.

This is not a speculative “AI-ready” wrapper. Heavy use led to 16 upstream defect fixes, plus fixes in this fork's own additions. Fourteen were landed as a reproducing test followed by the fix. The full, candid account—including the bugs introduced by this fork—is in AGENT_USABILITY_LEARNINGS.md.

Install

uv tool install mighty-colab

Or, with pip:

pip install mighty-colab

[!IMPORTANT] exec-async is available in v0.3.0. The new --json interface is currently on main and will ship in the next tagged release. To use it now:

uv tool install git+https://github.com/danbarua/mighty-colab

A 60-second agent workflow

Assuming Application Default Credentials are configured:

SESSION=agent-job

# Allocate a named runtime.
mighty-colab --auth=adc --json new -s "$SESSION" --gpu T4

# Capture the remote verdict as data, not terminal prose.
RESULT="$(mighty-colab --auth=adc --json exec \
  -s "$SESSION" -f job.py --timeout 3600)"

# Teardown happens before either verdict is propagated.
CLEANUP="$(mighty-colab --auth=adc --json stop -s "$SESSION")"

# Fail if either the remote job or cleanup failed.
jq -en --argjson job "$RESULT" --argjson cleanup "$CLEANUP" \
  '$job.status == "ok" and $cleanup.status == "ok"'

Global flags such as --auth, --json, and --config belong before the subcommand. For headless use, pass --auth=adc explicitly: the default OAuth2 flow opens a browser and needs a human.

For ADC setup, accelerator availability, recovery procedures, and the commands an agent must never invoke interactively, run:

mighty-colab skill

That manual is bundled with the installed CLI, so the agent's instructions stay versioned with the tool it is operating.

Machine-readable outcomes with --json

Every command commonly used in an agent loop—new, exec, run, exec-async, log --tail, status, sessions, and stop—can return one validated JSON envelope on stdout.

{
  "schema_version": "1",
  "cli_version": "<installed version>",
  "command": "exec",
  "status": "job_raised",
  "exit_code": 1
}

The important distinction is intentional:

• The CLI transaction answers “did the client complete its work?”
• The envelope's status and exit_code answer “what happened in the remote job?”

That separation avoids treating valid IPython results such as SystemExit(0) as client failures, while still making remote exceptions explicit. Envelopes also carry version information, stable reason values, backend http_status when available, structured outputs, and parse errors. Human-readable [colab] ... chatter moves to stderr, leaving stdout safe for jq or another programmatic caller.

Desired-state operations stay automation-friendly: stopping an already-absent session returns status: "ok" with reason: "already_stopped". Querying a missing named session is an error. That difference makes unconditional cleanup safe without hiding a real teardown failure.

See the live, end-to-end new → exec → exec-async → log → stop lifecycle for a complete jq-driven example.

Long jobs that fit short tool calls

Blocking on training for an hour is a poor fit for an agent harness or an MCP request/response cycle. Start the job in the background instead:

mighty-colab --auth=adc --json exec-async \
  -s trainer -f train.py --timeout 3600

The call returns in about a second with the PID and log path. Poll without blocking:

mighty-colab --auth=adc --json log \
  -s trainer --tail --since-offset 0

Use the returned next_offset on the next poll to avoid rereading old output. Only one background job runs per session, and a finished job never blocks the next one. Its terminal JSON result is written beside the log and survives session teardown, so an agent can recover the verdict later.

Recover instead of reallocating

Colab assignments live on the backend, while executable session metadata lives locally. A runtime created by another agent process—or by the Colab web UI—may therefore be visible to sessions but unavailable to exec.

# Bring one server-side runtime under local management.
mighty-colab adopt <ENDPOINT> -n recovered

# Or recover every orphaned assignment.
mighty-colab adopt --orphanage

Re-adopting the same endpoint also refreshes an expired runtime proxy token, without throwing away the VM and starting over. Add --keep-alive when the original owner is no longer keeping the session alive.

What this fork adds

The official colab README is the command reference for the base CLI. Mighty Colab keeps that surface and adds:

The fork also tightens failure behavior around remote exceptions, package installation, teardown, kernel and websocket cleanup, concurrent history, stream separation, and large uploads. See the CHANGELOG for the release-by-release detail.

The four rules agents should know

1. Always name sessions. Random names make recovery and multi-session work ambiguous.
2. Always pass --auth=adc for headless work. It is a global flag and must precede the subcommand.
3. Set --timeout deliberately. It limits the gap between outputs, not total wall-clock runtime. Quiet compilation or training often needs 3600 or more.
4. Always stop what you allocate. A session is a billable VM. Use unconditional teardown, or prefer run for a one-shot job that should clean itself up.

One more execution-model detail matters: exec -f script.py sends the local file's text into a live IPython kernel; it does not copy your repository onto the VM. Mighty Colab supplies sys.argv, __name__, and an honest synthetic __file__, but code that opens __file__ or sibling paths still needs the corresponding files uploaded or cloned remotely.

CLI, embedded MCP, or in-notebook MCP?

Minimal MCP client configuration:

{
  "mcpServers": {
    "mighty-colab": {
      "command": "uvx",
      "args": ["mighty-colab", "--auth", "adc", "mcp"]
    }
  }
}

TTY-bound commands are intentionally excluded, and log --follow is replaced by bounded log --tail polling. MCP results are currently plain text; structured MCP output is a known follow-up to the CLI's new JSON contract. See the MCP server design.

Read more

• What broke under heavy AI-agent usage—and what changed
• The bundled Colab operator skill
• Session and keep-alive architecture
• Execution, background jobs, and JSON output
• Ephemeral jobs with run
• SSH-over-WebSocket runtime access
• Embedded MCP server
• Demo walkthroughs

Contributing

External pull requests are not currently accepted, so contributions do not sit unreviewed. Ideas, bug reports, and agent pain points are very welcome in Discussions.

Mighty Colab is licensed under the Apache License 2.0.