Skip to content
Back to search

colab-studio

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/echohuhu--colab-studio/badge.svg)](/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
  1. # Colab Studio
  2. English | [中文说明](README_ZH.md)
  3. 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.
  4. ## Highlights
  5. - **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.
  6. - **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.
  7. - **Cost-Guard Protection (Prevent Runaway Billing)**:
  8. - **Min-VRAM Filtering (`min_vram_mib`)**: Automatically releases mismatched allocations (e.g., 40 GB vs 80 GB A100) and retries before starting workloads.
  9. - **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.
  10. - **Orphan `[?]` Runtime Detector**: Surfaces externally started runtimes consuming CU and lets you unassign them cleanly.
  11. - **Spend Cap & Floor Alerts**: Alerts immediately when remaining CU drops below `balanceFloorCu` or session cost exceeds `spendCapCu`.
  12. - **Automatic GGUF Quantisation & Hybrid KV-Cache Estimator**:
  13. - Reads remote GGUF binary headers over HTTP `Range` requests (`0..2 MiB`, via system proxy or `hf-mirror.com` fallback).
  14. - 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.
  15. - Precomputes exact fit matrices across `T4 (15 GB)`, `L4 (22.5 GB)`, `A100 (40 GB)`, and `A100 (80 GB)`.
  16. - **One-Click Declarative Plugins (`plugin.toml`)**:
  17. - `llama-cpp`: Prebuilt CUDA `llama-server` with dynamic GGUF auto-quant selection, `mmproj` multimodal support, and MTP speculative decoding.
  18. - `ollama`: Run Ollama with `hf.co/<owner>/<repo>:<quant>` or official tags.
  19. - `vllm`: High-throughput Hugging Face safetensors / AWQ / GPTQ / FP8 serving.
  20. - `comfyui`: Automated ComfyUI + Manager deployment on Colab GPUs.
  21. - Supports custom user plugins under `<dataDir>/plugins/`.
  22. - **Resilient Tunneling & Built-in Playground**:
  23. - 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.
  24. - **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.
  25. ---
  26. ## Architecture
  27. ```text
  28. +-------------------------------------------------------------------+
  29. | colab-studio (Single Go Binary) |
  30. | +-- cmd/colab-studio/main.go HTTP daemon & signal handler |
  31. | +-- internal/webui/ (embed.FS) React 19 + Vite + Tailwind |
  32. | +-- internal/server/ REST / SSE / Reverse Proxy |
  33. | | + Streamable HTTP /mcp |
  34. | +-- internal/backend/ Multi-account orchestrator, |
  35. | | SSH tunnel manager, reattach |
  36. | +-- internal/quant/ & hf/ Binary GGUF parser & VRAM fit|
  37. | +-- internal/plugins/ TOML manifest validator |
  38. | +-- internal/proxy/ Env + macOS scutil proxy |
  39. | +-- plugins/ & assets/ (embed.FS) Bundled workers + watchdog |
  40. +-------------------------------------------------------------------+
  41. | |
  42. | OS Keyring / Colab REST API | SSH Tunnel / Exec
  43. v v
  44. google-colab-cli (local Python) Google Colab GPU Runtime
  45. ```
  46. ---
  47. ## Prerequisites
  48. 1. **Go `1.23+`** (only required when building from source or installing via `go install`).
  49. 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.
  50. 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).
  51. 4. **Node.js + `pnpm`** *(only needed if modifying files in `web/` — prebuilt static assets are already committed in `internal/webui/dist/`)*.
  52. ---
  53. ## Quick Start
  54. ### Option 1: Install directly with Go
  55. ```bash
  56. go install github.com/echohuhu/colab-studio/cmd/colab-studio@latest
  57. colab-studio --port 4780
  58. ```
  59. Then open **http://127.0.0.1:4780**.
  60. ### Option 2: Build from Source
  61. ```bash
  62. git clone https://github.com/echohuhu/colab-studio.git
  63. cd colab-studio
  64. make build
  65. ./colab-studio --port 4780
  66. ```
  67. ### Frontend Development Mode
  68. When hacking on the React UI in `web/`, run the Go backend and Vite dev server together:
  69. ```bash
  70. # Terminal 1: Go API & MCP backend on :4780
  71. make dev
  72. # Terminal 2: Vite HMR dev server on :5173 (proxies /api and /mcp -> :4780)
  73. pnpm --dir web install
  74. pnpm --dir web dev
  75. ```
  76. Rebuild the embedded bundle whenever `web/` changes:
  77. ```bash
  78. make web && make build
  79. ```
  80. ---
  81. ## MCP Integration
  82. Point any MCP client supporting Streamable HTTP (`2025-03-26`) to:
  83. ```json
  84. {
  85. "mcpServers": {
  86. "colab-studio": {
  87. "url": "http://127.0.0.1:4780/mcp"
  88. }
  89. }
  90. }
  91. ```
  92. Available MCP tools:
  93. - `colab_get_overview`: Inspect accounts, CU balances, active sessions, tunnels, and runs.
  94. - `colab_provision_session`: Allocate a Colab GPU/TPU runtime with min-VRAM retries and watchdog timers.
  95. - `colab_stop_session`: Immediately terminate a named or orphan `[?]` Colab runtime to stop billing.
  96. - `colab_execute_code`: Execute Python on an active session via Colab CLI or Hosted MCP.
  97. - `colab_deploy_model`: Deploy `llama-cpp`, `ollama`, `vllm`, or `comfyui` and auto-forward `127.0.0.1` ports.
  98. ---
  99. ## Testing
  100. ```bash
  101. go vet ./...
  102. go test -v -race ./...
  103. ```
  104. The test suite verifies:
  105. - GGUF binary header metadata extraction & quant/KV fit parity against Python `plugins/llama-cpp/worker.py`.
  106. - TOML plugin manifest validation, security traversal checks, and Python syntax checks (`py_compile`).
  107. - 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`).
  108. ## License
  109. MIT © [echohuhu](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.