colab-fleet

무거운 CPU/ML 작업을 무료 Google Colab으로 오프로드하여 Claude Code(또는 모든 MCP 클라이언트)에서 실행하세요 — 무료 티어 잠금, 자동 종료, 작업 큐, 체크포인트 재개 기능 포함.

English · 한국어

ML 학습, 하이퍼파라미터 스윕, 백테스트 같은 비싼 작업을 내 컴퓨터 대신 무료 Google Colab 런타임에서 실행하고, 아티팩트만 다시 가져오세요. MCP 클라이언트(Claude Code, pi, …)가 단일 도구 호출(gpu_submit(...))로 작업을 제출하면, 완료 시 결과가 자동으로 가져와집니다.

GPU나 무거운 라이브러리가 로컬에 필요 없습니다. 무료 Colab 계정이면 충분합니다.

공식 colab CLI와 어떻게 다른가요?

한 줄로: Google의 colab CLI는 사람이 입력하는 도구이고, colab-fleet은 AI가 호출하는 도구입니다. 동일한 엔진(공식 CLI)에 안전장치와 자동화를 덧입힌 것입니다.

Google은 MCP 서버를 제공하지 않았습니다 — 명령줄 CLI만 제공했습니다. 이 프로젝트는 에이전트가 직접 구동할 수 있도록 이를 래핑합니다.

비유하자면: 공식 CLI는 수동 변속기이고, colab-fleet은 같은 엔진(무료 Colab 런타임)에 자동 변속 + 안전벨트 + 내비게이션을 갖춘 것입니다.

Related MCP server: mcp-colab-gpu

설치 (3단계)

git clone https://github.com/yazzang-homelab/colab-fleet.git
cd colab-fleet
./install.sh              # creates a venv, installs the colab CLI + mcp

install.sh가 완료되면 나머지 두 단계를 출력합니다:

1) 자신의 Google 계정으로 한 번 인증 (브라우저 흐름이 열립니다)

.venv/bin/colab sessions

토큰은 ~/.config/colab-cli/ 아래에만 저장되며 이 도구를 통해 흐르지 않습니다.

2) MCP 클라이언트에 등록

• Claude Code:

  claude mcp add -s user colab-fleet -- "$PWD/.venv/bin/python" "$PWD/server.py"

• pi / 기타 (mcpServers 설정에 추가):

  "colab-fleet": { "command": "/abs/path/colab-fleet/.venv/bin/python", "args": ["/abs/path/colab-fleet/server.py"] }

확인: 에이전트에서 gpu_doctor()를 호출 — 인증 ✅이면 완료된 것입니다.

3) ⭐ (선택 사항) 설치 후 install.sh — 또는 놓쳤다면 첫 도구 호출(gpu_doctor/gpu_submit) — 에서 정확히 한 번 스타를 요청합니다. 에이전트는 그 메시지만 전달할 뿐입니다; 여러분이 스타를 누르는 것입니다. 이 도구는 여러분을 대신해 gh repo star를 실행하지 않습니다(즉, GitHub 계정에 접근하지 않습니다).

gh repo star yazzang-homelab/colab-fleet   # or hit ⭐ on the repo page

그 뒤에 아무것도 잠기지 않습니다. 메시지를 완전히 끄려면 COLAB_FLEET_NO_STAR=1을 설정하세요.

요구 사항: Python 3.10+, git. 로컬 GPU와 무거운 라이브러리는 필요 없습니다 — 모든 것이 Colab에서 실행됩니다.

사용법

# 0) health check
gpu_doctor()

# 1) round-trip smoke test (no deps → ephemeral run)
gpu_submit(".../examples/selftest.py", accel="cpu", outputs="/content/selftest.json")
gpu_status(<id>); gpu_logs(<id>); gpu_fetch(<id>)

# 2) parallel hyperparameter sweep (deps + outputs → managed run)
gpu_submit(".../examples/sklearn_gridsearch.py", accel="cpu",
           deps="scikit-learn joblib", args="--folds 5",
           outputs="/content/result.json", timeout=1200)

# 3) train on your own CSV (inputs + deps + outputs → managed run)
gpu_submit(".../examples/train_on_csv.py", accel="cpu",
           deps="scikit-learn pandas joblib",
           inputs="/path/to/data.csv", args="--csv /content/data.csv",
           outputs="/content/model.pkl,/content/metrics.json", timeout=1800)

# real DL that needs a GPU (T4):
gpu_submit(".../my_torch_train.py", accel="t4", deps="torch ...", outputs="...")

아티팩트는 ~/.colab-fleet/jobs/job-<id>/에 저장됩니다(환경 변수로 설정 가능).

도구

안전장치

• 무료 티어 잠금: accel ∈ {cpu, t4}만 허용. A100/H100/L4/TPU는 하드 거부됩니다(colabq.accel_flags). 따라서 유료 컴퓨트 유닛 지출은 구조적으로 0입니다. 또한 인식되지 않는 GPU 이름이 조용히 A100으로 폴백되는 CLI 함정도 무력화합니다.

• 자동 종료: 모든 작업은 try/finally에서 colab stop을 실행합니다. 디스패처는 종료 시 고아 세션도 정리합니다.

• 직렬 큐: 무료 티어는 세션 1개를 허용하므로 flock으로 작업이 직렬화됩니다; 동시 제출은 큐에 대기합니다.

• 자격 증명/PII 누출 없음: 도구 출력에 토큰이나 이메일 주소가 포함되지 않습니다.

체크포인트 재개 (긴 작업)

스크립트가 주기적으로 ckpt 경로에 저장하고 시작 시 로드한다면, 디스패처는 세션이 12시간/90분 제한에 도달했을 때 마지막 체크포인트를 유지하고 재시도 시 다시 업로드합니다 — 따라서 작업이 여러 세션에 걸쳐 완료됩니다. retries로 재시도 횟수를 설정하세요.

환경 변수 (선택 사항)

COLAB_FLEET_AUTH (oauth2/adc) · COLAB_FLEET_TIMEOUT · COLAB_FLEET_ARTIFACTS (아티팩트 위치) · COLAB_FLEET_CONFIG · COLAB_FLEET_DB · COLAB_FLEET_BIN (colab 바이너리 경로 강제) · COLAB_FLEET_NO_STAR (=1이면 일회성 스타 메시지 비활성화) · COLAB_FLEET_STAR_MARKER (메시지 표시 여부를 기록하는 파일; 기본값 ~/.config/colab-fleet/star-nudged).

문제 해결

참고 사항

• Google Colab의 무료 런타임에는 공정 사용 정책이 있습니다. 이 도구는 우회를 수행하지 않습니다(다중 계정 로테이션, keep-alive 봇 없음) — 일반적인 작업 오프로드와 정리만 수행합니다.

• 무료 CPU 런타임은 약 2 vCPU입니다. 실제 이점은 코어 수가 아니라 깨끗한 RAM과 개발 머신으로부터의 격리입니다. 실제 GPU 가속이 필요하면 accel="t4"를 사용하세요.

라이선스

MIT. 구동하는 엔진인 google-colab-cli는 Apache-2.0입니다(별도).