colabsh

A CLI tool for Google Colab. Execute code, download notebooks, and interact with Google Colab directly from your terminal. Connects through your browser via WebSocket. No API keys needed.

Table of Contents

• Installation
• Quick Start
• How It Works
• Auto Mode (Playwright)
• Commands
• Headless Mode
• Security
• Configuration
• Docker
• Development
• Architecture
• License

Installation

Quick Start

# Start the server (opens Google Colab in browser once)
colabsh start

# Execute code (reuses the same browser tab)
colabsh exec "print('hello from Google Colab')"
colabsh exec -f script.py
echo "import sys; print(sys.version)" | colabsh exec -

# Interactive REPL with readline history
colabsh repl

# Download notebook
colabsh download notebook.ipynb
colabsh download script.py -f analysis.py

# Stop the server when done
colabsh stop

How It Works

Terminal                     Background Server              Browser
--------                     -----------------              -------
colabsh start ---------------> WebSocket server <----------> Colab
colabsh exec "code" ----TCP--> routes to Colab -----------> executes
colabsh exec "more" ----TCP--> same connection -----------> executes
colabsh stop ----------------> shuts down

1. colabsh start launches a background server and opens Colab in your browser
2. Colab's frontend connects back via WebSocket (MCP proxy protocol)
3. All subsequent commands go through this persistent connection
4. One browser tab serves all commands, no new tabs per command
5. The server auto-starts if you run exec/repl without starting first

Auto Mode (Playwright)

For fully headless operation with no manual browser interaction. Playwright controls a real Chrome browser to connect to Colab automatically.

Setup

pip install colabsh[auto]
playwright install chromium

# Login once (opens a visible browser)
colabsh login

# Then use auto mode
colabsh start --auto

GPU selection

# Select GPU on start
colabsh start --auto --gpu t4

# Change GPU while running
colabsh gpu t4
colabsh gpu a100
colabsh gpu cpu

Available GPU types: cpu, t4, a100, v100, l4, tpu

Health check

colabsh status --health

Shows runtime type (CPU/GPU), whether the runtime is alive, and connection state.

Debugging

# Show the browser window
colabsh start --auto --show-browser

# Check server log
cat ~/.config/colabsh/server.log

Commands

Server

Execute

REPL Features

Download

Other

Headless Mode

For SSH sessions, containers, or remote machines where there's no desktop browser:

colabsh start --headless

This prints the connection URL instead of opening a browser. Open the URL on the same machine in any browser.

SSH Port Forwarding

To use colabsh on a remote server:

# On remote server
colabsh start --headless
# Output: https://colab.research.google.com/notebooks/empty.ipynb#mcpProxyToken=...&mcpProxyPort=45123

# On your local machine (forward the port)
ssh -L 45123:localhost:45123 remote-server

# Open the printed URL in your local browser
# It connects to localhost:45123 which is forwarded to the remote server

# Now run commands on the remote server
colabsh exec "print('running on remote')"

Why not LAN/phone access? Google Colab's frontend JavaScript always connects WebSocket to localhost. This is hardcoded in Google's code. When you open the URL on a different device, the browser tries to connect to localhost on that device, which doesn't have the colabsh server. The only workaround is SSH port forwarding, which makes the remote port appear as localhost on your local machine.

Security

What colabsh does

• Runs a localhost-only WebSocket server, not accessible from the network
• Uses a random authentication token for every session
• Communicates with Google Colab via Google's MCP proxy protocol
• Stores data locally in your config directory. Nothing is sent to third parties

What to be aware of

• The connection URL contains a secret token. Treat it like a password
• Anyone with the URL can execute code in your Colab session
• The background server runs until you stop it (colabsh stop)
• Code execution happens on Google's Colab VMs, subject to Google's terms of service
• The Google Colab session has your Google account's permissions

Token lifecycle

Configuration

Config directory

Config files

Output format

Human-readable output is the default:

colabsh status
# status: running
# connected: true
# pid: 12345

colabsh --json status
# {"status": "running", "connected": true, "pid": 12345}

Use --json when piping to other tools or LLMs.

Docker

# Build
docker build -t colabsh .

# Login (interactive, mount profile volume)
docker run -it -v colabsh-data:/root/.config/colabsh colabsh login

# Run with auto-connect
docker run -d -v colabsh-data:/root/.config/colabsh colabsh start --auto

# Execute code
docker exec <container> colabsh exec "print('hello')"

Development

Architecture

src/colabsh/
|-- main.py              # Click CLI entry point
|-- commands.py          # All commands (exec, repl, start, stop, gpu, login, ...)
|-- history.py           # history list/show/clear/toggle
+-- core/
    |-- models.py        # Pydantic models (Settings, ServerState, ConnectionInfo)
    |-- config.py        # Platform config dirs, settings persistence
    |-- server.py        # Background server (WebSocket + TCP control)
    |-- proxy.py         # WebSocket + JSON-RPC to Colab frontend
    |-- browser.py       # Playwright automation (auto-connect, GPU, login)
    |-- cells.py         # Shared helpers for notebook cell parsing
    |-- output.py        # JSON/human formatter
    |-- history.py       # Local usage tracking
    |-- repl.py          # Shared REPL with readline
    +-- qr.py            # QR code generation (optional)

License

Apache-2.0

Inspiration

Inspired by colab-mcp but with a focus on CLI usability, persistent server, and local history.

Disclaimer

This project has no affiliation with Google. It reverse-engineers Google Colab's frontend protocol to enable terminal access. Use responsibly and in accordance with Google's terms of service.