Back to search
colab-studio
MCP serverGitHub
Single-binary Go + embedded React console & MCP server for Google Colab GPU deployment, multi-account CU monitoring, and SSH/Cloudflare tunneling
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/echohuhu--colab-studio)HTML
<a href="/listings/echohuhu--colab-studio"><img src="/api/listings/echohuhu--colab-studio/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Option 1: Install directly with Go
go install github.com/echohuhu/colab-studio/cmd/colab-studio@latest colab-studio --port 4780
Then open **http://127.0.0.1:4780**.
Option 2: Build from Source
git clone https://github.com/echohuhu/colab-studio.git cd colab-studio make build ./colab-studio --port 4780
Frontend Development Mode
When hacking on the React UI in `web/`, run the Go backend and Vite dev server together:
# Terminal 1: Go API & MCP backend on :4780 make dev # Terminal 2: Vite HMR dev server on :5173 (proxies /api and /mcp -> :4780) pnpm --dir web install pnpm --dir web dev
Rebuild the embedded bundle whenever `web/` changes:
make web && make build
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 143 lines
- # Colab Studio
- English | [中文说明](README_ZH.md)
- Single-binary **Go + Embedded React Console + Local MCP Server** for orchestrating Google Colab GPUs, guarding Compute Units (CU), managing multiple accounts, forwarding local SSH / Cloudflare public tunnels, and deploying GGUF / vLLM / Ollama / ComfyUI workloads in one click.
- ## Highlights
- - **Single Go Binary (Zero Runtime Assets Needed)**: Built in Go (`1.23+`) with the production Vite + React 19 + Tailwind CSS v4 frontend (`internal/webui/dist`), built-in TOML plugins (`plugins/`), and VM Python helpers (`assets/`) embedded directly via Go `embed.FS`. Only `github.com/BurntSushi/toml` is used outside the Go standard library.
- - **Multi-Account Isolation & Quota Dashboard**: Safely manages multiple Google Colab accounts via your OS keyring + isolated per-account `sessions.json`, monitors Compute Unit (CU) balance & hourly burn rate, and auto-detects eligible GPU/TPU specs via Google Colab's REST API (`colaboratory.googleapis.com/v1beta`) with seamless CLI fallback.
- - **Cost-Guard Protection (Prevent Runaway Billing)**:
- - **Min-VRAM Filtering (`min_vram_mib`)**: Automatically releases mismatched allocations (e.g., 40 GB vs 80 GB A100) and retries before starting workloads.
- - **Detached VM Watchdog (`assets/watchdog.py`)**: Enforces both max-runtime (`defaultAutoStopMinutes`) and idle-timeout (`defaultIdleStopMinutes`) shutdown on the Colab VM itself so billing stops even if your laptop sleeps or loses network.
- - **Orphan `[?]` Runtime Detector**: Surfaces externally started runtimes consuming CU and lets you unassign them cleanly.
- - **Spend Cap & Floor Alerts**: Alerts immediately when remaining CU drops below `balanceFloorCu` or session cost exceeds `spendCapCu`.
- - **Automatic GGUF Quantisation & Hybrid KV-Cache Estimator**:
- - Reads remote GGUF binary headers over HTTP `Range` requests (`0..2 MiB`, via system proxy or `hf-mirror.com` fallback).
- - Understands hybrid linear/full attention architectures (`full_attention_interval`), per-layer KV arrays, multi-token prediction (`mtp` / `nextn_predict_layers`), `mmproj` vision projectors, shard files, and `-draft-` exclusions.
- - Precomputes exact fit matrices across `T4 (15 GB)`, `L4 (22.5 GB)`, `A100 (40 GB)`, and `A100 (80 GB)`.
- - **One-Click Declarative Plugins (`plugin.toml`)**:
- - `llama-cpp`: Prebuilt CUDA `llama-server` with dynamic GGUF auto-quant selection, `mmproj` multimodal support, and MTP speculative decoding.
- - `ollama`: Run Ollama with `hf.co/<owner>/<repo>:<quant>` or official tags.
- - `vllm`: High-throughput Hugging Face safetensors / AWQ / GPTQ / FP8 serving.
- - `comfyui`: Automated ComfyUI + Manager deployment on Colab GPUs.
- - Supports custom user plugins under `<dataDir>/plugins/`.
- - **Resilient Tunneling & Built-in Playground**:
- - Single-flight OpenSSH `-L` local port forwarding (`ProxyCommand` via `colab ssh --proxy-mode`) with automatic `HTTP 429` slot-reap retry, optional `trycloudflare.com` quick tunnels, streaming reverse proxy (`/api/runs/<id>/proxy/*`), and restart-resilient VM reattachment.
- - **Local Streamable HTTP MCP Server (`/mcp`)**: Exposes `colab_get_overview`, `colab_provision_session`, `colab_stop_session`, `colab_execute_code`, and `colab_deploy_model` for AI coding agents and IDEs.
- ---
- ## Architecture
- ```text
- +-------------------------------------------------------------------+
- | colab-studio (Single Go Binary) |
- | +-- cmd/colab-studio/main.go HTTP daemon & signal handler |
- | +-- internal/webui/ (embed.FS) React 19 + Vite + Tailwind |
- | +-- internal/server/ REST / SSE / Reverse Proxy |
- | | + Streamable HTTP /mcp |
- | +-- internal/backend/ Multi-account orchestrator, |
- | | SSH tunnel manager, reattach |
- | +-- internal/quant/ & hf/ Binary GGUF parser & VRAM fit|
- | +-- internal/plugins/ TOML manifest validator |
- | +-- internal/proxy/ Env + macOS scutil proxy |
- | +-- plugins/ & assets/ (embed.FS) Bundled workers + watchdog |
- +-------------------------------------------------------------------+
- | |
- | OS Keyring / Colab REST API | SSH Tunnel / Exec
- v v
- google-colab-cli (local Python) Google Colab GPU Runtime
- ```
- ---
- ## Prerequisites
- 1. **Go `1.23+`** (only required when building from source or installing via `go install`).
- 2. **`google-colab-cli`** (`colab` CLI installed in your PATH, e.g. via `uv tool install google-colab-cli`), signed in once or managed via the UI Accounts page.
- 3. **OpenSSH (`ssh`)** and an SSH public key (`~/.ssh/id_ed25519.pub` or `~/.ssh/id_ecdsa.pub`, can also be generated from the UI Settings page).
- 4. **Node.js + `pnpm`** *(only needed if modifying files in `web/` — prebuilt static assets are already committed in `internal/webui/dist/`)*.
- ---
- ## Quick Start
- ### Option 1: Install directly with Go
- ```bash
- go install github.com/echohuhu/colab-studio/cmd/colab-studio@latest
- colab-studio --port 4780
- ```
- Then open **http://127.0.0.1:4780**.
- ### Option 2: Build from Source
- ```bash
- git clone https://github.com/echohuhu/colab-studio.git
- cd colab-studio
- make build
- ./colab-studio --port 4780
- ```
- ### Frontend Development Mode
- When hacking on the React UI in `web/`, run the Go backend and Vite dev server together:
- ```bash
- # Terminal 1: Go API & MCP backend on :4780
- make dev
- # Terminal 2: Vite HMR dev server on :5173 (proxies /api and /mcp -> :4780)
- pnpm --dir web install
- pnpm --dir web dev
- ```
- Rebuild the embedded bundle whenever `web/` changes:
- ```bash
- make web && make build
- ```
- ---
- ## MCP Integration
- Point any MCP client supporting Streamable HTTP (`2025-03-26`) to:
- ```json
- {
- "mcpServers": {
- "colab-studio": {
- "url": "http://127.0.0.1:4780/mcp"
- }
- }
- }
- ```
- Available MCP tools:
- - `colab_get_overview`: Inspect accounts, CU balances, active sessions, tunnels, and runs.
- - `colab_provision_session`: Allocate a Colab GPU/TPU runtime with min-VRAM retries and watchdog timers.
- - `colab_stop_session`: Immediately terminate a named or orphan `[?]` Colab runtime to stop billing.
- - `colab_execute_code`: Execute Python on an active session via Colab CLI or Hosted MCP.
- - `colab_deploy_model`: Deploy `llama-cpp`, `ollama`, `vllm`, or `comfyui` and auto-forward `127.0.0.1` ports.
- ---
- ## Testing
- ```bash
- go vet ./...
- go test -v -race ./...
- ```
- The test suite verifies:
- - GGUF binary header metadata extraction & quant/KV fit parity against Python `plugins/llama-cpp/worker.py`.
- - TOML plugin manifest validation, security traversal checks, and Python syntax checks (`py_compile`).
- - Full lifecycle integration testing of `RealBackend`, HTTP APIs, MCP JSON-RPC, min-VRAM retries, secret redaction, and VM reattachment against an isolated mock `colab` CLI harness (`tests/fake/colab_shim.py`).
- ## License
- MIT © [echohuhu](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.