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 로 감싼 게 이 프로젝트입니다.

항목	공식 colab CLI (날것)	colab-fleet (이 래퍼)
누가 쓰나	사람이 터미널에서 직접	AI 가 대화 중 gpu_submit(...) 호출
비용 사고 방지	A100·TPU 등 유료 가속기 그냥 붙음(과금)	무료(cpu/t4)만 허용, 유료 하드 거부 → 결제 0
타임아웃	기본 30초 — ML 돌리면 중간에 끊김	잡마다 길게(기본 1시간) + 체크포인트로 이어감
세션 정리	깜빡하면 켜진 채 방치	끝나면 자동 종료, 고아 세션도 청소
동시 실행	무방비(무료는 세션 1개라 충돌)	큐로 한 줄로 줄세움
데이터	사람이 직접 업/다운로드	입력 자동 업로드 → 실행 → 결과 자동 회수
자격/비밀	사용자가 알아서	토큰·이메일을 출력에 절대 안 흘림

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

---

설치 (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>/ 로 내려옵니다(환경변수로 변경 가능).

도구 목록

도구	설명
gpu_submit(script, accel, deps, args, inputs, outputs, ckpt, timeout, retries, label)	잡 제출(비동기), 잡 id 반환
gpu_status(job_id=0)	잡 상세 / 0 이면 최근 잡 + 활성 세션
gpu_logs(job_id, lines)	단계별 로그 tail
gpu_fetch(job_id)	산출물 경로 나열
gpu_sessions()	활성 Colab 세션
gpu_stop(name="all")	세션 중단(유닛 보호)
gpu_doctor()	헬스·인증·큐 상태

---

가드레일

• 무료티어 락: 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 경로 강제).

트러블슈팅

증상	원인/조치
gpu_doctor 인증 ❌	1회 로그인 미완 → .venv/bin/colab sessions 로 브라우저 인증
401/403	스코프 부족 → 재로그인(또는 COLAB_FLEET_AUTH=adc + gcloud auth application-default login)
GPU 미할당(400 on new)	무료 T4 가용성 변동 → accel="cpu" 폴백
잡이 queued 만	디스패처 미기동 → .venv/bin/python dispatch.py 수동 실행
업로드 500/실패	colab upload=Jupyter API라 입력 1개 ~80MB 초과 시 500. 서브셋/압축으로 축소. 디스패처가 업로드 실패를 잡 실패로 표시(은폐 안 함)
done 인데 결과 없음	원격 스크립트 예외 → 성공 sentinel 미출력 → 실패처리. gpu_logs 의 stderr Traceback 확인

주의

• Google Colab 무료 런타임은 공정사용 정책이 있습니다. 이 도구는 다계정·세션 유지 봇 같은 우회를 하지 않으며, 정상 범위의 잡 오프로드·자동 정리만 합니다.
• 무료 CPU 런타임은 대략 2 vCPU 수준 — 코어 수보다 깨끗한 RAM + 내 개발 PC와의 격리가 실익입니다. 진짜 GPU 가속이 필요하면 accel="t4".

라이선스

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