colab-fleet

Offload heavy CPU/ML work to free Google Colab from Claude Code (or any MCP client) — with a free-tier lock, auto-teardown, a job queue, and checkpoint-resume.

무거운 연산(ML 학습·하이퍼파라미터 스윕·백테스트)을 내 PC 대신 무료 Google Colab 런타임에서 돌리고, 그 결과만 받아오는 도구입니다. Claude Code·pi 같은 MCP 클라이언트가 도구 한 번 호출(gpu_submit(...))로 잡을 보내고, 끝나면 산출물을 자동으로 회수합니다.

내 컴퓨터엔 무거운 라이브러리도, GPU도 필요 없습니다. Colab 계정(무료) 하나면 됩니다.

공식 colab CLI 와 뭐가 다른가 (쉽게)

한 줄: Google 의 colab CLI 는 "사람이 손으로 치는 도구", colab-fleet 은 "AI 가 알아서 부르는 도구". 엔진은 같은 공식 CLI 를 쓰되, 위에 안전장치와 자동화를 얹었습니다.

Google 은 공식 MCP 서버를 안 만들었습니다. 나온 건 명령줄 CLI 뿐. 그래서 AI 가 바로 쓰도록 MCP 로 감싼 게 이 프로젝트입니다.

비유하면 공식 CLI = 수동 변속기, colab-fleet = 그 위의 자동 변속 + 안전벨트 + 내비. 엔진(무료 Colab 런타임)은 같지만, AI 가 사고 없이 자동으로 굴리게 만든 것.

Related MCP server: mcp-colab-gpu

설치 (3스텝)

git clone https://github.com/yazzang-homelab/colab-fleet.git
cd colab-fleet
./install.sh              # venv 생성 + colab CLI·mcp 설치

install.sh 가 끝나면 남은 2가지를 안내해 줍니다:

1) 본인 Google 계정으로 1회 인증 (브라우저 흐름이 열립니다)

.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() → auth ✅ 면 끝.

요구사항: Python 3.10+, git. GPU·무거운 라이브러리는 내 PC에 불필요(전부 Colab에서 실행).

사용

# 0) 헬스체크
gpu_doctor()

# 1) 왕복 검증 (의존성 0 → ephemeral run)
gpu_submit(".../examples/selftest.py", accel="cpu", outputs="/content/selftest.json")
gpu_status(<id>); gpu_logs(<id>); gpu_fetch(<id>)

# 2) 병렬 하이퍼파라미터 스윕 (deps + outputs → managed)
gpu_submit(".../examples/sklearn_gridsearch.py", accel="cpu",
           deps="scikit-learn joblib", args="--folds 5",
           outputs="/content/result.json", timeout=1200)

# 3) 내 CSV 업로드해서 학습 (inputs + deps + outputs → managed)
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)

# GPU(T4) 가 필요한 진짜 DL 이면:
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. CLI 의 '미인식 GPU 무음 A100 폴백' 풋건 무력화.

• 자동 teardown: 모든 잡은 try/finally 로 colab stop. 디스패처 종료 시 고아 세션도 회수.

• 직렬 큐: 무료티어는 세션 1개 → flock 으로 한 줄 처리, 동시 제출은 큐잉.

• 자격/PII 미노출: 도구 출력에 토큰·이메일 없음.

체크포인트-리줌 (장시간 잡)

스크립트가 ckpt 경로에 주기 저장 + 시작 시 있으면 로드·재개하면, 세션이 12h/90분 캡에 끊겨도 디스패처가 마지막 체크포인트를 보관했다가 재시도 때 되올려 여러 세션에 걸쳐 완주합니다. retries 로 재시도 횟수 지정.

환경변수 (선택)

COLAB_FLEET_AUTH(oauth2/adc) · COLAB_FLEET_TIMEOUT · COLAB_FLEET_ARTIFACTS(산출물 위치) · COLAB_FLEET_CONFIG · COLAB_FLEET_DB · COLAB_FLEET_BIN(colab 경로 강제).

트러블슈팅

주의

• Google Colab 무료 런타임은 공정사용 정책이 있습니다. 이 도구는 다계정·세션 유지 봇 같은 우회를 하지 않으며, 정상 범위의 잡 오프로드·자동 정리만 합니다.

• 무료 CPU 런타임은 대략 2 vCPU 수준 — 코어 수보다 깨끗한 RAM + 내 개발 PC와의 격리가 실익입니다. 진짜 GPU 가속이 필요하면 accel="t4".

라이선스

MIT. 엔진으로 쓰는 google-colab-cli 는 Apache-2.0(별도).