#!/usr/bin/env bash set -euo pipefail echo "[colab-lab] Initializing starter workspace in: $(pwd)" mkdir -p data examples scripts outputs : > outputs/.gitkeep cat <<'__COLAB_STARTER_EOF__' > data/sales_sample.csv date,region,product,units,unit_price 2026-11-01,East,GPU-Credit-Pack,12,25.0 2026-11-01,West,Colab-Pro-Seat,5,10.0 2026-11-02,East,Colab-Pro-Seat,8,10.0 2026-11-02,North,TPU-Lab-Pass,4,40.0 2026-11-03,West,GPU-Credit-Pack,10,25.0 2026-11-03,South,Colab-Pro-Seat,6,10.0 2026-11-04,North,GPU-Credit-Pack,7,25.0 2026-11-04,South,TPU-Lab-Pass,3,40.0 __COLAB_STARTER_EOF__ cat <<'__COLAB_STARTER_EOF__' > requirements-demo.txt tabulate>=0.9.0 humanize>=4.10.0 __COLAB_STARTER_EOF__ cat <<'__COLAB_STARTER_EOF__' > examples/01_hw_probe.py """Hardware, OS, environment variable, and GPU probe for Colab CLI tutorials. Run remotely on an active session: colab exec -s demo -f examples/01_hw_probe.py --env STAGE=tutorial """ from __future__ import annotations import os import platform import shutil import socket import subprocess import sys def _get_memory_gb() -> tuple[float, float] | None: """Return (total_gb, available_gb) on Linux or macOS when inspectable.""" meminfo = "/proc/meminfo" if os.path.exists(meminfo): values: dict[str, int] = {} with open(meminfo, "r", encoding="utf-8") as f: for line in f: key, rest = line.split(":", 1) kb = int(rest.strip().split()[0]) values[key] = kb total_kb = values.get("MemTotal") avail_kb = values.get("MemAvailable", values.get("MemFree")) if total_kb and avail_kb is not None: return total_kb / (1024**2), avail_kb / (1024**2) if platform.system() == "Darwin": try: out = subprocess.check_output(["sysctl", "-n", "hw.memsize"], text=True).strip() total_gb = int(out) / (1024**3) return total_gb, total_gb except Exception: return None return None def _probe_gpu() -> str: """Inspect NVIDIA GPU via nvidia-smi and optional PyTorch CUDA.""" lines: list[str] = [] nvsmi = shutil.which("nvidia-smi") if nvsmi: try: res = subprocess.run( [ nvsmi, "--query-gpu=name,memory.total,driver_version", "--format=csv,noheader", ], check=True, capture_output=True, text=True, ) gpu_info = res.stdout.strip() or "nvidia-smi returned empty output" lines.append(f"nvidia-smi : {gpu_info}") except Exception as exc: lines.append(f"nvidia-smi : failed ({exc})") else: lines.append("nvidia-smi : not available (CPU / TPU runtime)") try: import torch # type: ignore cuda_ok = torch.cuda.is_available() lines.append(f"torch.cuda : available={cuda_ok}") if cuda_ok: lines.append(f"device[0] : {torch.cuda.get_device_name(0)}") except ImportError: lines.append("torch.cuda : PyTorch not installed in this environment") return "\n".join(lines) def main() -> None: disk_target = "/content" if os.path.isdir("/content") else os.getcwd() usage = shutil.disk_usage(disk_target) mem = _get_memory_gb() print("=== Colab Runtime Probe ===") print(f"Hostname : {socket.gethostname()}") print(f"OS : {platform.platform()}") print(f"Python : {sys.version.split()[0]}") print(f"WorkingDir : {os.getcwd()}") print(f"CPU Cores : {os.cpu_count()}") if mem: print(f"Memory : total={mem[0]:.2f} GB, available={mem[1]:.2f} GB") else: print("Memory : unavailable") print( f"Disk ({disk_target}): " f"total={usage.total / (1024**3):.2f} GB, " f"free={usage.free / (1024**3):.2f} GB" ) print(f"ENV STAGE : {os.environ.get('STAGE', '')}") print(_probe_gpu()) if __name__ == "__main__": main() __COLAB_STARTER_EOF__ cat <<'__COLAB_STARTER_EOF__' > examples/02_plot_demo.py """Generate a two-panel matplotlib chart and emit PNG display output for `colab exec`. Run remotely and capture the chart directly to a local file: colab exec -s demo -f examples/02_plot_demo.py --output-image outputs/cloud_plot.png """ from __future__ import annotations import io import math import os def main() -> None: import matplotlib matplotlib.use("Agg") import matplotlib.pyplot as plt xs = [i * 0.1 for i in range(0, 63)] sin_ys = [math.sin(x) for x in xs] cos_ys = [math.cos(x) for x in xs] categories = ["CPU", "T4", "L4", "A100"] throughput = [12, 85, 140, 310] fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(10, 4), dpi=130) ax1.plot(xs, sin_ys, label="sin(x)", linewidth=2, color="#1a73e8") ax1.plot(xs, cos_ys, label="cos(x)", linewidth=2, linestyle="--", color="#e37400") ax1.set_title("Trigonometric Waves (Cloud Rendered)") ax1.set_xlabel("x (radians)") ax1.set_ylabel("amplitude") ax1.grid(True, alpha=0.3) ax1.legend() bars = ax2.bar(categories, throughput, color=["#5f6368", "#34a853", "#1a73e8", "#a142f4"]) ax2.set_title("Illustrative Relative Throughput") ax2.set_ylabel("samples / sec") ax2.grid(True, axis="y", alpha=0.3) for bar, val in zip(bars, throughput): ax2.text( bar.get_x() + bar.get_width() / 2, val + 6, str(val), ha="center", va="bottom", fontsize=9, ) fig.tight_layout() buf = io.BytesIO() fig.savefig(buf, format="png") plt.close(fig) png_bytes = buf.getvalue() save_dir = "/content" if os.path.isdir("/content") else "outputs" os.makedirs(save_dir, exist_ok=True) save_path = os.path.join(save_dir, "cloud_plot.png") with open(save_path, "wb") as f: f.write(png_bytes) print(f"Saved PNG copy on runtime at: {save_path} ({len(png_bytes)} bytes)") try: from IPython.display import Image, display # type: ignore display(Image(data=png_bytes)) except ImportError: print("IPython not available; skipped inline display.") if __name__ == "__main__": main() __COLAB_STARTER_EOF__ cat <<'__COLAB_STARTER_EOF__' > examples/03_notebook_demo.ipynb { "cells": [ { "cell_type": "markdown", "id": "nb-cell-001", "metadata": {}, "source": [ "# Colab CLI Notebook Execution Demo\n", "\n", "Use `colab exec -s demo -f examples/03_notebook_demo.ipynb` to execute every code cell on the remote Colab kernel.\n", "Outputs will be written automatically to `examples/03_notebook_demo_output.ipynb`." ] }, { "cell_type": "code", "execution_count": null, "id": "nb-cell-002", "metadata": {}, "outputs": [], "source": [ "# @title 1. 环境与算力检查\n", "import os\n", "import platform\n", "import socket\n", "import sys\n", "\n", "print(f\"Host : {socket.gethostname()}\")\n", "print(f\"OS : {platform.system()} {platform.release()}\")\n", "print(f\"Python : {sys.version.split()[0]}\")\n", "print(f\"CWD : {os.getcwd()}\")" ] }, { "cell_type": "code", "execution_count": null, "id": "nb-cell-003", "metadata": {}, "outputs": [], "source": [ "# @title 2. 跨单元格计算与统计\n", "matrix = [\n", " [1.5, 2.0, 3.5],\n", " [4.0, 5.5, 6.0],\n", " [7.5, 8.0, 9.5],\n", "]\n", "flat = [val for row in matrix for val in row]\n", "row_sums = [sum(row) for row in matrix]\n", "mean_val = sum(flat) / len(flat)\n", "max_val = max(flat)\n", "\n", "print(f\"Matrix shape : {len(matrix)}x{len(matrix[0])}\")\n", "print(f\"Row sums : {row_sums}\")\n", "print(f\"Mean value : {mean_val:.4f}\")\n", "print(f\"Max value : {max_val:.4f}\")" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "name": "python", "version": "3.11" } }, "nbformat": 4, "nbformat_minor": 5 } __COLAB_STARTER_EOF__ cat <<'__COLAB_STARTER_EOF__' > examples/04_process_data.py """Aggregate sales_sample.csv on Colab VM and export JSON + Markdown reports. Typical remote pipeline: colab upload -s demo data/sales_sample.csv /content/sales_sample.csv colab exec -s demo -f examples/04_process_data.py colab download -s demo /content/summary_report.json outputs/summary_report.json """ from __future__ import annotations import csv import json import os from collections import defaultdict def _resolve_paths() -> tuple[str, str, str]: """Choose /content paths on Colab VM or local workspace paths for dry-runs.""" if os.path.exists("/content/sales_sample.csv"): return ( "/content/sales_sample.csv", "/content/summary_report.json", "/content/summary_table.md", ) if os.path.isdir("/content"): raise FileNotFoundError( "/content/sales_sample.csv not found. Upload it first via:\n" " colab upload -s demo data/sales_sample.csv /content/sales_sample.csv" ) os.makedirs("outputs", exist_ok=True) return ( os.path.join("data", "sales_sample.csv"), os.path.join("outputs", "summary_report.json"), os.path.join("outputs", "summary_table.md"), ) def _format_table(headers: list[str], rows: list[list[object]]) -> str: """Render a clean Markdown table, preferring `tabulate` if installed.""" try: from tabulate import tabulate # type: ignore return tabulate(rows, headers=headers, tablefmt="github", floatfmt=".2f") except ImportError: lines = [ "| " + " | ".join(headers) + " |", "| " + " | ".join(["---"] * len(headers)) + " |", ] for row in rows: formatted = [f"{v:.2f}" if isinstance(v, float) else str(v) for v in row] lines.append("| " + " | ".join(formatted) + " |") return "\n".join(lines) def main() -> None: input_csv, out_json, out_md = _resolve_paths() by_region: dict[str, dict[str, float]] = defaultdict(lambda: {"units": 0, "revenue": 0.0}) by_product: dict[str, dict[str, float]] = defaultdict(lambda: {"units": 0, "revenue": 0.0}) total_units = 0 total_revenue = 0.0 row_count = 0 with open(input_csv, "r", encoding="utf-8", newline="") as f: reader = csv.DictReader(f) for row in reader: row_count += 1 units = int(row["units"]) revenue = units * float(row["unit_price"]) region = row["region"] product = row["product"] total_units += units total_revenue += revenue by_region[region]["units"] += units by_region[region]["revenue"] += revenue by_product[product]["units"] += units by_product[product]["revenue"] += revenue region_rows = [ [region, int(stats["units"]), round(stats["revenue"], 2)] for region, stats in sorted(by_region.items(), key=lambda kv: -kv[1]["revenue"]) ] product_rows = [ [product, int(stats["units"]), round(stats["revenue"], 2)] for product, stats in sorted(by_product.items(), key=lambda kv: -kv[1]["revenue"]) ] report = { "source_file": input_csv, "rows_processed": row_count, "total_units": total_units, "total_revenue": round(total_revenue, 2), "by_region": { r: {"units": u, "revenue": rev} for r, u, rev in region_rows }, "by_product": { p: {"units": u, "revenue": rev} for p, u, rev in product_rows }, } with open(out_json, "w", encoding="utf-8") as f: json.dump(report, f, indent=2, ensure_ascii=False) f.write("\n") region_table = _format_table(["Region", "Units", "Revenue ($)"], region_rows) product_table = _format_table(["Product", "Units", "Revenue ($)"], product_rows) md_text = ( "# Sales Summary Report\n\n" f"- Rows processed: `{row_count}`\n" f"- Total units: `{total_units}`\n" f"- Total revenue: `${total_revenue:.2f}`\n\n" "## Revenue by Region\n\n" f"{region_table}\n\n" "## Revenue by Product\n\n" f"{product_table}\n" ) with open(out_md, "w", encoding="utf-8") as f: f.write(md_text) print(f"Processed {row_count} rows from {input_csv}") print(f"Wrote JSON report -> {out_json}") print(f"Wrote MD report -> {out_md}\n") print(region_table) if __name__ == "__main__": main() __COLAB_STARTER_EOF__ cat <<'__COLAB_STARTER_EOF__' > examples/05_ephemeral_job.py """Ephemeral one-shot cloud job demonstrating `colab run` CLI features. Examples: # 1. Run with forwarded args and redirect clean JSON stdout to a local file colab run examples/05_ephemeral_job.py --samples 100000 --seed 42 > outputs/monte_carlo.json # 2. Pass an environment variable colab run --env JOB_TAG=v1 examples/05_ephemeral_job.py --samples 50000 # 3. Verify exit code propagation (VM still auto-cleans!) colab run examples/05_ephemeral_job.py --fail-demo; echo "exit=$?" """ from __future__ import annotations import argparse import json import math import os import random import socket import sys def estimate_pi(samples: int, seed: int) -> float: rng = random.Random(seed) inside = 0 for _ in range(samples): x = rng.random() y = rng.random() if x * x + y * y <= 1.0: inside += 1 return 4.0 * inside / samples def main() -> None: parser = argparse.ArgumentParser(description="Monte Carlo Pi estimation job") parser.add_argument("--samples", type=int, default=50000, help="Number of random points") parser.add_argument("--seed", type=int, default=42, help="PRNG seed") parser.add_argument( "--fail-demo", action="store_true", help="Exit with status code 3 to test `colab run` exit-code propagation", ) args = parser.parse_args() if args.fail_demo: print( "[job] --fail-demo triggered: exiting with code 3", file=sys.stderr, ) sys.exit(3) if args.samples <= 0: print("[job] --samples must be positive", file=sys.stderr) sys.exit(2) pi_est = estimate_pi(args.samples, args.seed) payload = { "job_tag": os.environ.get("JOB_TAG", "default"), "host": socket.gethostname(), "argv": sys.argv, "samples": args.samples, "seed": args.seed, "pi_estimate": round(pi_est, 6), "abs_error": round(abs(pi_est - math.pi), 6), } print(json.dumps(payload, indent=2, ensure_ascii=False)) if __name__ == "__main__": main() __COLAB_STARTER_EOF__ cat <<'__COLAB_STARTER_EOF__' > examples/06_shebang_cloud.py #!/usr/bin/env -S colab run # 若想直接免管理申请 T4 GPU 跑完即销毁,可把首行改成: # #!/usr/bin/env -S colab run --gpu T4 # 若想跑完保留会话以便后续 colab exec / colab ssh 调试,可加上 --keep: # #!/usr/bin/env -S colab run --keep """Executable Python script that transparently runs on a fresh Colab VM via shebang. Usage after `chmod +x examples/06_shebang_cloud.py`: ./examples/06_shebang_cloud.py hello colab """ from __future__ import annotations import os import platform import socket import sys def main() -> None: print("=== Running via Colab Shebang (`#!/usr/bin/env -S colab run`) ===") print(f"Remote Hostname : {socket.gethostname()}") print(f"Remote Platform : {platform.platform()}") print(f"Remote CWD : {os.getcwd()}") print(f"Python Version : {sys.version.split()[0]}") print(f"Forwarded argv : {sys.argv}") if __name__ == "__main__": main() __COLAB_STARTER_EOF__ cat <<'__COLAB_STARTER_EOF__' > examples/ssh_config.snippet # ============================================================================== # Google Colab CLI — OpenSSH / VS Code / Cursor Remote-SSH 配置片段 # ============================================================================== # 使用前确认: # 1. Colab 服务端仅接受 Ed25519 或 ECDSA 公钥,拒绝 RSA (id_rsa)! # 若 ~/.ssh/ 下还没有对应密钥,请先生成: # ssh-keygen -t ed25519 -C "colab-cli" # 2. 将下方片段追加到 ~/.ssh/config 后,即可直接: # ssh colab-dev # 或在 VS Code / Cursor 的 Remote-SSH 插件里选择对应 Host 连接。 # (注:如果图形化 IDE 启动时未加载 ~/.local/bin 到 PATH,可把下方的 `colab` # 改为绝对路径,例如 `~/.local/bin/colab`) # 3. 注意:每个 Colab 实例的并发 SSH 连接数有上限(常见 1~5 个,视账号套餐而定), # 超限会报 HTTP 429;用完请及时断开或 colab stop。 # ============================================================================== # 1. 常驻开发机:连接名为 dev 的会话(首次连接若不存在会自动创建 CPU 会话) Host colab-dev HostName colab-runtime User root ProxyCommand colab ssh --proxy-mode -s dev StrictHostKeyChecking no UserKnownHostsFile /dev/null LogLevel ERROR # 2. 用完即焚的 T4 GPU 工作站:连接时自动申请 T4,断开 SSH 后自动销毁回收算力(--rm) Host colab-t4-ephemeral HostName colab-runtime User root ProxyCommand colab ssh --proxy-mode -s t4box --gpu T4 --rm StrictHostKeyChecking no UserKnownHostsFile /dev/null LogLevel ERROR __COLAB_STARTER_EOF__ cat <<'__COLAB_STARTER_EOF__' > scripts/smoke_test.sh #!/usr/bin/env bash set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)" cd "${ROOT_DIR}" SESSION="tutorial-smoke" mkdir -p outputs banner() { echo echo "======================================================================" echo "$1" echo "======================================================================" } banner "Step 1/8: 检查 Colab CLI 版本与当前认证身份 (colab version & whoami)" colab version colab whoami # 确保脚本中途报错或 Ctrl-C 时仍会自动释放远端 VM,避免算力空转 trap 'colab stop -s "${SESSION}" >/dev/null 2>&1 || true' EXIT banner "Step 2/8: 申请免费 CPU 会话并查看状态 / 浏览器挂载 URL" colab new -s "${SESSION}" colab status -s "${SESSION}" echo -n "Browser Attach URL: " colab url -s "${SESSION}" banner "Step 3/8: 验证 Kernel 跨调用持久状态 (两次 exec 共享内存变量)" echo 'magic_num = 2026; print("Set magic_num =", magic_num)' | colab exec -s "${SESSION}" echo 'print("Read magic_num from next exec call ->", magic_num * 2)' | colab exec -s "${SESSION}" banner "Step 4/8: 运行硬件与环境变量探针 (01_hw_probe.py + --env)" colab exec -s "${SESSION}" -f examples/01_hw_probe.py --env STAGE=smoke-test banner "Step 5/8: 云端 Matplotlib 绘图并直接截获为本地 PNG (--output-image)" colab exec -s "${SESSION}" -f examples/02_plot_demo.py --output-image outputs/cloud_plot.png banner "Step 6/8: 双向文件流水线 (upload -> ls -> exec -> download)" colab upload -s "${SESSION}" data/sales_sample.csv /content/sales_sample.csv colab ls -s "${SESSION}" content colab exec -s "${SESSION}" -f examples/04_process_data.py colab download -s "${SESSION}" /content/summary_report.json outputs/summary_report.json banner "Step 7/8: 导出完整会话执行日志为 Jupyter Notebook 与 Markdown" colab log -s "${SESSION}" -o outputs/session_replay.ipynb colab log -s "${SESSION}" -o outputs/session_report.md banner "Step 8/8: 显式释放会话并汇总本地产出文件" colab stop -s "${SESSION}" echo echo "Smoke test 完成!outputs/ 目录当前产出:" ls -lh outputs/ __COLAB_STARTER_EOF__ chmod +x examples/06_shebang_cloud.py scripts/smoke_test.sh cat <<'__COLAB_MSG_EOF__' ====================================================================== Colab CLI Starter Lab 已就绪! ====================================================================== 目录包含:data/ · examples/ · scripts/smoke_test.sh · outputs/ 推荐 3 步开跑: 1. colab version || uv tool install google-colab-cli 2. colab whoami # 首次运行按提示在浏览器授权并粘贴授权码 3. ./scripts/smoke_test.sh # 在免费 CPU 实例上跑通全流程并自动释放 提示:单独体验请参考教程网站或逐个运行 examples/ 下的脚本。 ====================================================================== __COLAB_MSG_EOF__