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 · Run unattended jobs

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.

What goes wrong for an agent	What Mighty Colab provides
A remote script raises, but the caller cannot reliably tell what happened	Schema-validated --json envelopes with separate CLI and remote-job outcomes
Training outlives a shell or MCP tool call	exec-async returns immediately; log --tail provides bounded, incremental polling
A long run must finish, upload its results and release the VM with nobody watching	job: a spec-driven run, detached from the kernel, with a recorded verdict and a retry class
The agent restarts while the Colab VM keeps running	Server-side session discovery, adopt, orphan recovery, and durable result sidecars
Cleanup runs on every path, including partial failure	Idempotent stop for already-absent sessions; genuine teardown failures stay loud and retryable
Multiple agent processes touch the same local state	Locked history plus --config isolation for parallel runs
Human-friendly output becomes parser-hostile noise	JSON-only stdout, chatter on stderr, stable reason codes, and ANSI-stripped tracebacks

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

A 60-second agent workflow

Assuming Application Default Credentials are configured. Every response below was captured live against a real CPU runtime — nothing fabricated. Swap in --gpu T4 / --gpu A100 on new for accelerated workloads (add --high-mem for a high-RAM machine shape, Colab Pro/Pro+ required); the envelope shape is identical either way.

SESSION=agent-job
echo 'print("hello from mighty-colab")' > job.py

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

{
  "schema_version": "1",
  "cli_version": "<installed version>",
  "command": "new",
  "status": "ok",
  "exit_code": 0,
  "session": "agent-job",
  "endpoint": "m-s-kkb-use1c1-2ol526ollah5r",
  "variant": "DEFAULT",
  "accelerator": "NONE"
}

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

{
  "schema_version": "1",
  "cli_version": "<installed version>",
  "command": "exec",
  "status": "ok",
  "exit_code": 0,
  "blocks": [
    {
      "code": "import sys\nsys.argv = ['job.py']\n__name__ = '__main__'\n__file__ = '<mighty-colab-exec:job.py>'\nprint(\"hello from mighty-colab\")\n",
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": "hello from mighty-colab\n"
        }
      ],
      "cell_index": null,
      "cell_id": null
    }
  ]
}

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

{
  "schema_version": "1",
  "cli_version": "<installed version>",
  "command": "stop",
  "status": "ok",
  "exit_code": 0,
  "session": "agent-job"
}

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

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.

Background runs 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.

Unattended runs with job

exec-async runs a script in a session you manage: you install the packages, move the files, read the log, decide the outcome and stop the VM. job does all of that for you. You describe the run in a YAML spec; job provisions the VM, installs the dependencies, stages the code and data, and launches the run as a process detached from the kernel, so a dropped connection does not end it. When the run ends, job uploads the artifacts, releases the VM, and records the outcome:

mighty-colab --auth=adc --json job plan job.yaml            # validates; allocates nothing
mighty-colab --auth=adc --json job apply --job-id <id> --async
mighty-colab --auth=adc --json job status <id> --poll       # waits for the outcome

The envelope reports the workload, the uploads and the release separately. When something failed, it names the phase that failed (failed_phase) and what to do next (retry_class: fix_code, fix_human, retry_same, retry_different, refresh_urls or do_not_retry), with the HTTP status, response body or installer output that explains it. If the process that started the job dies, job status --poll collects the result and releases the VM. See docs/job/README.md.

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 refreshes its runtime access metadata without throwing away the VM. 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:

Addition	Agent benefit
job / jobs	Unattended, spec-driven runs that provision, install, stage, upload and release on their own, and record a verdict with a retry class
--json	Versioned, validated outcomes instead of scraping prose
exec-async	Start long work without holding a caller open
log --tail --since-offset	Bounded, incremental polling for agents and MCP clients
adopt [ENDPOINT] / adopt --orphanage	Recover runtimes created by another process or UI
reinstall	Install packages and restart the kernel so cached imports really update
mcp	Expose non-interactive CLI commands as MCP tools, with the --json envelope as structured content and job records as resources
--debug	Opt into verbose client and transport diagnostics
sync [--git-aware]	Gzip a file tree before transfer; optionally retain sparse Git identity and selected worktree status
usage	Compute-unit balance, hourly consumption and eligible accelerators, also as --json; each job envelope records the balance at provision and release
--no-keepalive on new, run, job apply	Start no keep-alive daemon. Upstream states that Colab's backend now keeps runtimes alive based on kernel activity and active connections
Chunked uploads	Move large files without the single-request failure mode

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?

You want to…	Use…
Drive Colab from shell scripts, CI, Make, or an external coding agent	mighty-colab CLI
Expose the same non-interactive workflow to an MCP client	mighty-colab mcp
Add interactive agent assistance inside a Colab notebook	Google's colab-mcp
Use the supported upstream command surface without this fork's additions	Google's colab CLI

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. A tool whose command supports --json returns the envelope as structured content beside the text. Job records are resources (job://<id>, job://<id>/logs, jobs://), and a job://<id> subscription sends a notification when the workload leaves pending and when the job is done. See the MCP server design and docs/job/mcp.md.

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
• Unattended runs with job
• 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.