GPUPlane

Agent-native training control plane for personal & small-scale GPU environments.

個人 GPU トレーニングのコントロールプレーン：タスクのキューイングとスケジューリング、リアルタイム指標/ログ、チェックポイント登録、イベント診断 —— Agent（MCP）とブラウザのために生まれ、SSH + tmux + 目視での loss 監視はもう不要です。

製品ドキュメントサイト：https://ericyuan2007.github.io/GPUPlane/（クイックスタート / ガイド / MCP ツールリファレンス）； 設計ドキュメントは docs/（プロダクト調査 / プロダクト設計 / システム設計 / MVP ロードマップ）、 ドキュメントサイトの設計ドキュメントアーカイブでも閲覧できます。

機能（v0.1）

• トレーニングコードに非侵入：python train.py は常に単独で実行可能。GPUPlane はプロセスホスティングと観測のみを行い、SDK は完全にオプションで、トレーニングプロセスに例外を投げることは決してありません。

• GPU スロットスケジューリング：カード単位で排他割り当て（利用率で空きを推測しない）、優先度キュー、失敗時の自動リトライ（OOM を除く）、CUDA_VISIBLE_DEVICES の自動注入。

• ３段階のメトリクス連携：TensorBoard ディレクトリのリアルタイム tail（L1、変更不要）、SDK による直接報告（L2、from gpuctl import run）、システムメトリクス NVML（L3）。

• ログ：agent の全量ディスク保存 + server の末尾 2000 行 + SSE リアルタイムストリーム。gpuctl logs -f で直接追跡できます。

• Checkpoint 発見：watch ディレクトリのデバウンススキャン、step に応じて best 指標と関連付け。

• イベントセマンティクス層：LOSS_NAN / OOM / DISK_LOW / ライフサイクルイベントを、ルールエンジンで決定的に判定。

• SQLite 単一ファイル：Kafka/Redis/Postgres 不要、WAL モード、1コマンドでオンラインバックアップ。

• オフラインレジリエンス：agent はローカル jsonl spool に保存し、切断時はリプレイ。server 側はカーソルによる冪等な重複排除で、agent を再起動しても失われず重複しません。

Related MCP server: Train in Silence

機能（v0.2、検収済み）

• 実験管理：Project/Experiment CRUD と run のグループ化。Web UI Experiments ページ + run 比較ビュー（複数 run の指標重ね合わせ、best 順ソート）。

• 評価のクローズドループ：POST /checkpoints/{id}/evaluations で EVALUATE job をキューイング（トレーニング job の working_dir/リソースを継承）→ 結果を run に追加 → GET /checkpoints:recommend が primary metric で checkpoint を推奨。

• 完全なイベントルール：LOSS_SPIKE / OVERFITTING_SUSPECTED / GPU_UNDERUTILIZED / DISK_LOW、プロセス内スライディングウィンドウ + デバウンス。

• 失敗分類リトライ：OOM / EXIT_CODE / DISPATCH_FAILED は自動リトライせず、それ以外は max_attempts に従って再スケジュール。

• DockerRunner：ProcessRunner と同等のセマンティクス（ログ/終了コード/スロット）、--gpus 注入、docker kill によるキャンセル。

• イベント外部プッシュ：server.yaml で ntfy/Bark webhook を設定（severity/type フィルタ、best-effort）；gpuctl event-hook でイベントストリームからローカルスクリプトを起動。

• フレームワーク callbacks：gpuctl.callbacks は Lightning / HF Trainer の薄いラッパーを提供、オプションのインポートでゼロ依存。

• MetricDefinition UI：direction と global/project/experiment の primary をビジュアル編集。解決順は experiment → project → global で、checkpoint 推奨を駆動。

機能（v0.3、検収済み）

• Agent-native（MCP）：gpuctl-mcp は独立プロセス/パッケージ（fastmcp 3.4.7 pin 固定）で 21 個のツール を公開——11 observe + 5 control + 5 semantic。streamable HTTP ステートレス中核。失敗しても server に影響しません（design §15）。

• セマンティクス層（LLM なし）：diagnose_run / compare_runs / compare_checkpoints / get_best_checkpoint / explain_failure の 5 つの純 Python 関数（ルール + 統計）。REST と MCP はいずれも薄い公開層です。各結果には next_actions が含まれ Agent を次のステップへ誘導するため、ポーリング不要です。

• 3 つの Skill：run-experiment / monitor-experiment / analyze-results（.claude/skills/gpu-training/）。6 フィールドの frontmatter、allowed-tools で MCP ツールを事前に承認し、「提出→監視→比較→推奨」のループがコード化されています。

• プラグインパッケージング：.claude-plugin/plugin.json（stdio MCP + skills + hooks で配布可能）；.mcp.json（http、gitignored）。

• AGENTS.md：リポジトリレベルの agent ルール（canonical、CLAUDE.md はミラー）——素のプロセス+SQLite のレッドライン、実験ループ、metric / job / ckpt の規約、OOM runbook。

• 読み書きスコープ分離：GET /auth/whoami は {name, scope, can_write} を公開。書き込み操作（submit / cancel / retry / evaluate）には write-scope トークンが必要で、読み取り専用トークンは WriteScopeError を返します。

検収結果：Agent は自然言語 + MCP のみで、人の手によるプラットフォーム操作なしに「トレーニングの提出 → 監視 → 比較 → 推奨」の全ループを完遂。詳細は docs/08-v0.3-acceptance.md。

クイックスタート（30 分でデプロイできる標準）

環境：Python ≥3.12、uv。

git clone <repo> && cd GPUPlane
uv sync                          # 安装全部组件（server/agent/cli/sdk）

# 1. 启动 server（GPU 机器上；首启自动生成 admin token 写入 ~/.gpuctl/server.yaml）
uv run gpuctl-server

# 2. 启动 agent（同机；token 从 server.yaml 复制到 ~/.gpuctl/agent.yaml）
uv run gpuctl-agent

# 3. 提交训练（cpu_only 示例先跑通，再上 GPU）
uv run gpuctl job submit -n mnist -g 1 \
  -d "$PWD/examples/mnist" --watch checkpoints \
  -- python train.py --epochs 3

# 注意：-d/--working-dir 按【agent 所在机器】解释，CLI 不做本地改写；
# 从笔记本向远端提交时传远端绝对路径。

# 4. 观测
uv run gpuctl status             # 节点/队列总览
uv run gpuctl job list           # 任务状态
uv run gpuctl logs -f <job-id>   # 实时日志
uv run gpuctl run show <run-id>  # 指标摘要（latest/best/trend）

# 5. Web UI（server 自动托管 web/dist；也可用 GPUCTL_WEB_DIST 指定）
open http://<gpu-host>:8600      # 输入 token 登录

履歴実験のインポート（TB events + checkpoints → IMPORTED run）：

uv run gpuctl import-run ~/experiments/old-run --project legacy

速度制限 / オフラインインストール

依存は約 50 個の小さな wheel のみ（torch はプラットフォームの依存ではないため、トレーニングマシンの既存環境で十分）。ネットワーク制限時は、インターネットに繋がるマシンで事前にダウンロードし、ターゲットマシンへコピーしてオフラインインストールします：

# 在能上网的机器（如 Mac）上，为 Linux x86_64 + py3.12 下载
uv export --format requirements-txt --locked --no-hashes --no-dev -o /tmp/reqs.txt
grep -v '^-e ' /tmp/reqs.txt > /tmp/reqs-clean.txt
uv run --python 3.12 --with pip python -m pip download -r /tmp/reqs-clean.txt hatchling editables \
  --python-version 312 --only-binary=:all: \
  --platform manylinux_2_28_x86_64 --platform manylinux_2_17_x86_64 \
  --platform manylinux2014_x86_64 -d ./wheels
rsync -az ./ ./wheels/ gpu-host:~/GPUPlane-wheels/   # 含仓库本体

# 目标机（离线）
cd ~/GPUPlane && uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python --no-index --find-links ~/GPUPlane-wheels \
  -r ~/GPUPlane-wheels/reqs-clean.txt hatchling editables
uv pip install --python .venv/bin/python --no-index --no-build-isolation \
  -e ./packages/common -e ./packages/tbreader -e ./packages/sdk \
  -e ./packages/server -e ./packages/agent -e ./packages/cli

2 つのデプロイメントトポロジー

同一マシン（推奨の入門構成）：server + agent を GPU マシン上で実行し、ラップトップのブラウザ/CLI から LAN 経由でアクセス（server.yaml で host: 0.0.0.0 を設定、トークン認証）。

分離構成：server は常時稼働の軽量マシン（Mac mini / NAS でも可）で実行、agent は各 GPU マシンで実行。agent.yaml の server_url が server の ws://<ip>:8600 を指定します。agent は一方向に悪さをしない常時接続を張り、GPU マシンはインバウンドポートを一切不要とし、切断時は自動再接続 + spool リプレイします。

イベントをスマートフォンに通知 / ローカルからの自動操作（v0.2）

~/.gpuctl/server.yaml に webhook を追加（ntfy の例；Bark は kind: bark + デバイス URL を使う）：

webhooks:
  - url: "https://ntfy.sh/my-gpu-topic"   # 手机装 ntfy 订阅同一 topic
    kind: ntfy
    min_severity: warning                  # info|warning|critical，低于此不推
    # types: ["OOM", "LOSS_NAN"]           # 可选：只推这些事件类型

ローカルでの自動化（イベント到着時にローカルで即座にコマンドを実行、例：ローカル agent の起動）：

gpuctl event-hook --severity critical -- /path/to/on-event.sh
# 事件经 GPUCTL_EVENT_TYPE/SEVERITY/MESSAGE/RUN_ID/... 环境变量 + stdin JSON 传入

Agent-native：自然言語で実験ループを操作（v0.3）

gpuctl-mcp は独立した adapter プロセス（server/agent に依存しない）で、コントロールプレーンを 21 個の MCP ツールとして公開します。設定後、Claude Code（または任意の MCP クライアント）は自然言語で「トレーニング提出 → 異常監視 → checkpoint 比較 → 推奨」を、Web/CLI に一切触れないまま完了できます：

# 1. 起 adapter（独立进程；指向 server，带 write-scope token）
GPUCTL_SERVER_URL=http://127.0.0.1:8600 GPUCTL_MCP_TOKEN=<write-token> \
  gpuctl-mcp serve --port 18602            # streamable HTTP, stateless
# stdio 形态（插件用）：gpuctl-mcp stdio

# 2. 让 Claude Code 发现它（仓库根 .mcp.json，已 gitignore）
cat > .mcp.json <<'JSON'
{ "mcpServers": { "gpuctl": { "type": "http",
  "url": "http://127.0.0.1:18602/mcp",
  "headers": { "Authorization": "Bearer <write-token>" } } } }
JSON

# 3. 自然语言驱动（skill 自动加载，无需手点工具）
claude -p "提交一个 mnist 训练，跑完告诉我结果，再对比最近两次 run 给我最好的 checkpoint"

prefixs: 書き込みスコープの分離：読み取り専用トークン時、submit_job / cancel_job / retry_job / evaluate_checkpoint / set_primary_metric は WriteScopeError を返す。 3 つのスキル（.claude/skills/gpu-training/）が実験ループをコード化し、MCP ツールを事前承認します。詳細は docs/08-v0.3-acceptance.md を参照。

トレーニング側 SDK（オプション）

from gpuctl import run

run.init(project="qwen-sft", experiment="lr-2e5", config={...})   # 平台 job 内自动 attach，可省略
run.log({"train/loss": loss.item()}, step=step)                   # 有界队列，绝不阻塞/抛错
run.log_checkpoint(path, step=step)                               # 只登记，不搬运文件
run.finish()

プラットフォームがディスパッチした job 内ではゼロ構成（env 自動注入）。プラットフォーム外で実行すると source=sdk の run を自動で登録。server がない場合はサイレントにローカル jsonl（~/.gpuctl/spool/）へ任意的に降格し、トレーニングスクリプトの動作は完全に変わりません。

アーキテクチャ

┌────────────┐   WS (出站)   ┌──────────────┐    REST/SSE    ┌──────────┐
│  Agent(s)  │ ───────────► │    Server    │ ◄────────────  │ CLI/Web  │
│ monitor/   │  heartbeat   │  scheduler   │                │ (同源)   │
│ runner/tb  │  metrics/logs│  SQLite(WAL) │ ◄──── HTTP ─── │ SDK      │
└────────────┘              └──────────────┘                └──────────┘

monorepo：packages/{common,server,agent,sdk,cli,mcp,tbreader} + web/ + examples/mnist + .claude/skills/（agent skills）+ .claude-plugin/。packages/mcp は独立した adapter プロセスで、server/agent に依存しません。

運用基本

uv run gpuctl backup             # 在线备份 SQLite 到 <data_dir>/backups/
uv run gpuctl backup-agent       # 在每台 Agent 主机归档完整 job 日志/runtime/spool
# 常驻运行见 deploy/systemd/（user unit + enable-linger）
uv run gpuctl job retry <id>     # 失败任务重新排队
uv run gpuctl job cancel <id>    # SIGTERM → 5s → SIGKILL（整进程组）
uv run pytest tests/ -q          # Python 测试（当前 145 个用例）
cd web && pnpm test:e2e          # 浏览器 smoke（2 个用例）
uv run ruff check . && uv run mypy

Docker runner は任意機能。Process runner は現時点では既定です。GPU コンテナを使用する前、Agent ホストはまず NVIDIA 公式インストールガイド に従って Container Toolkit をインストールし、runtime を Docker 構成に書き込む必要があります：

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker       # 先确认没有运行中的容器
docker run --rm --gpus all <cuda-image> nvidia-smi

WSL2 上では、まずホスト委譲が正常に動作していること（nvidia-smi で GPU が見える）を確認してください。Toolkit は委譲された GPU をコンテナに公開するのみで、Windows/WSL ドライバの代替にはなりません。

設計上のレッドライン（コントリビュート前の必読）

1. トレーニングコードの独立性：python train.py はプラットフォームを離れても常に利用可能であること。

2. best-effort telemetry：要件があってもすべてローカルバッファに皮に落とすだけで、トレーニングプロセスには決して例外を投げない。

3. Process runner がファーストクラスです。Docker/Git を強制しません。

4. GPU スケジュールングはスロット単位の排他で行い、利用率から空きを判断することは決してない。

5. Job ≠ Run：Job はスケジューリング単位、Run はトレーニングの意味単位（1 回の attempt に 1 つの Run）。

6. SQLite + メッセージキューなし。server は単一 worker（インメモリ pub/sub は意図的な選択）。

License

GPUPlane is licensed under the Apache License 2.0. Attribution information is in NOTICE.