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 ロードマップ）、 ドキュメントサイトの設計ドキュメントアーカイブでも閲覧できます。
トレーニングコードに非侵入：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: colab-autopilot
実験管理：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 推奨を駆動。
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。
環境：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同一マシン（推奨の入門構成）：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 リプレイします。
~/.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 传入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 を参照。
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 mypyDocker 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-smiWSL2 上では、まずホスト委譲が正常に動作していること（nvidia-smi で GPU が見える）を確認してください。Toolkit は委譲された GPU をコンテナに公開するのみで、Windows/WSL ドライバの代替にはなりません。
トレーニングコードの独立性：python train.py はプラットフォームを離れても常に利用可能であること。
best-effort telemetry：要件があってもすべてローカルバッファに皮に落とすだけで、トレーニングプロセスには決して例外を投げない。
Process runner がファーストクラスです。Docker/Git を強制しません。
GPU スケジュールングはスロット単位の排他で行い、利用率から空きを判断することは決してない。
Job ≠ Run：Job はスケジューリング単位、Run はトレーニングの意味単位（1 回の attempt に 1 つの Run）。
SQLite + メッセージキューなし。server は単一 worker（インメモリ pub/sub は意図的な選択）。
GPUPlane is licensed under the Apache License 2.0. Attribution information is in NOTICE.
This server cannot be deployed
GPU compute for agents: run commands on an L4/A100/H100, watch logs, billed per second.
On-demand GPU nodes for agents: create nodes, run commands, and submit jobs, billed by the minute.
Deploy and manage your apps, databases, storage, and scheduled jobs from your AI agent
Your AI Agent's Infrastructure Layer. Connect Claude, Copilot, Codex, or ChatGPT to 200+ managed open source services. Start databases, pipelines, and applications through natural language.
