Agent-native Trainings-Kontrollplan für private & kleine GPU-Umgebungen. Die Steuerungsebene für privates GPU-Training: Auftragswarteschlange und Scheduling, Echtzeitmetriken/Logs, Checkpoint-Registrierung, Ereignisdiagnose – gebaut für Agenten (MCP) und Browser, nicht mehr abhängig von SSH + tmux und dem Beobachten der Loss-Kurve mit bloßem Auge.
Produktdokumentationseite: https://ericyuan2007.github.io/GPUPlane/ (Schnellstart / Anleitungen / MCP-Werkzeugreferenz); Systemdokumentation in
docs/(Produktrecherche / Produktdesign / Systemdesign / MVP-Fahrplan), auch lesbar unter dem Archiv der Systemdokumente der Dokumentationsseite.
Null invasive Integration für Trainingscode: python train.py bleibt jederzeit eigenständig ausführbar; GPUPlane übernimmt nur Prozessverwaltung und Beobachtung. Das SDK ist vollständig optional und wirft niemals eine Ausnahme in den Trainingsprozess.
GPU-Slot-Planung: exklusive Zuweisung pro GPU-Karte (keine Ableitung von freien Slots anhand der Auslastung), Prioritätswarteschlange, automatische Wiederholung bei Fehlern (außer OOM), automatische Injektion von CUDA_VISIBLE_DEVICES.
Dreistufige Metrikanbindung: Live-Tail auf TensorBoard-Verzeichnisse (L1, keine Codeänderung), SDK-Direktmeldungen (L2, from gpuctl import run), NVML-Systemmetriken (L3).
Logs: vollständige Festplatten-Protokollierung im Agenten + letzte 2000 Zeilen am Server + SSE-Stream in Echtzeit, mit gpuctl logs -f direkt verfolgbar.
Checkpoint-Erkennung: überwachte Verzeichnisse mit Entprell-Scanning, Zuordnung von Bestmetriken zum jeweiligen Schritt.
Events-Sementik: LOSS_NAN / OOM / DISK_LOW / Lebenszyklus-Ereignisse, deterministische Bewertung durch die Regelengine.
SQLite als Einzeldatei: kein Kafka/Redis/Postgres, WAL-Modus, Online-Backup mit einem einzigen Befehl.
Offline-Resil: lokaler JSONL-Spool beim Agent, Wiedergabe nach Verbindungsabbruch; serverseitiger Cursor mit idempotenter Deduplizierung – nach Agent-Neustart weder Verluste noch Duplikate.
Related MCP server: colab-autopilot
Experimente-Verwaltung: CRUD für Project/Experiment und Gruppierung von Runs; Experiments-Seite in der Web-UI + Run-Vergleichsansicht (Metriken mehrer Runs überlegen, Beitrag über Sortierung nach Bestwert).
Geschlossener Evaluierungskreislauf: POST /checkpoints/{id}/evaluations protokolliert einen EVALUATE-Auftrag (erbt working_dir/Ressourcen des Trainingsjobs) → Ergebnis wird zurückgeschrieben → GET /checkpoints:recommend empfiehlt Checkpoints anhand der primären Metrik.
Vollständige Ereignisregeln: LOSS_SPIKE / OVERFITTING_SUSPECTED / GPU_UNDERUTILIZED / DISK_LOW, mit rollierendem Fenster im Prozess und Debouncing.
Wiederholung nach Fehlertyp: OOM / EXIT_CODE / DISPATCH_FAILED nie automatisch wiederholt, alle anderen Fehler werden nach max_attempts neu eingereiht.
DockerRunner: gleiche Semantik wie ProcessRunner (Logs/Exitcodes/Slots), Injektion von --Generate, region via docker kill.
Ereignisweiterleitung: server.yaml für ntfy/Bark-Webhooks (Filter nach severity/typ, best-effort); gpuctl event-hook weckt ein lokales Skript durch den Ereignis-Stream.
Framework-Callbacks: gpuctl.callbacks für Lightning / HF Trainer, dünne Wrapper, optional importierbar, keine Abhängigkeiten.
MetricDefinition-UI: sichtbare Bearbeitung von Richtung und primärer Metrik (global/project/experiment); Shapesosungsunterschied: experiment → project → global, steuert Checkpoint-Empfehlung.
Agent-native (MCP): gpuctl-mcp als unabhängiger Prozess/Paket (fastmcp 3.4.7 gepinnt) exponoughs 21 Werkzeuge – 11 observe + 5 control + 5 semantic; streamable HTTP, statistischer Kern. Ein Ausfall beeinträchtigt den Server nach Design §15 nicht.
Semantische Schicht (ohne LLM): diagnose_run / compare_runs / compare_checkpoints / get_best_checkpoint / explain_failure – fünf pure Python-Funktionen (Regeln + Statistik), Unit REST und MCP sind nur dünne Expositionsschichten; jede Antwort enthält next_actions, um den Agenten ohne Polling zum nächsten Schritt zu führen.
3 Skills: run-experiment / monitor-experiment / analyze-results (.claude/skills/gpu-training/), 6 Felder Frontmatter, allowed-tools vorstandard für MCP-Werkzeuge; der Lifecycle „Einreichen → Überwachen → Vergleichen → Empfehlen“ codiert darin.
Plugin-Bündelung: .claude-plugin/plugin.json (stdio-MCP + Skills + Hooks verteilbar); .mcp.json (http, gitignored).
AGENTS.md: Repo-weite Agent-Regeln (kanonisch, in CLAUDE.md gespiegelt) – blank-Process + SQLite als rote Linien, Experiment-Lebenszyklus, Metrik/Job/Checkpoint-Konventionen, OOM-Runbook.
Lese-Schreib-Abstufung: GET /auth/whoami liefert {name, scope, can_write}, Schreiboperationen (submit/cancel/retry/evaluate) verlangen ein Token mit write-Bereich; schreibgeschützte Token erhalten WriteScopeError.
Abnahme: Der Agent bewältigt den gesamten Zyklus „Training senden → überwachen → vergleichen → empfehlen“, allein mit natürlicher Sprache und MCP – ohne Handplattform-Interaktion. Siehe
docs/08-v0.3-acceptance.md.
Umgebung: 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 登录Import vorhandener Experimente (TensorBoard-Events + Checkpoints → Imported Run):
uv run gpuctl import-run ~/experiments/old-run --project legacyNur Anzahl wenig kleine Wheels nötig (torch ist keine Abhängigkeit – vorhandene Trainingsumgebung reicht). In Netzwerkumgebungen mit Abschnitten auf einer zugänglichen Maschine vorab laden, auf die Zielmaschine kopieren und offline installieren:
# 在能上网的机器（如 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/cliGleiche Maschine (empfohlener Einstieg): Server und Agent laufen auf GPU-Maschine, Browser und CLI über LAN zugänglich (host: 0.0.0.0 in server.yaml, Token-Authentifizierung).
Getrennte: Server läuft auf einer dauerhaft verfügbaren Leichtmaschine (auch Mac mini/NAS), Agenten auf den einzelnen GPU-Maschinen; agent.yaml zeigt mit server_url auf ws://<ip>:8600 des Servers. Der Agent hält eine reine Ausgangs-Langverbindung, die GPU-Maschinen brauchen keinerlei eingehenden Ports, nach einer Trennung gibt es automatisches Wiederverw.:
Webhook in ~/.gpuctl/server.yaml (ntfy-Beispiel; Bark mit kind: bark + Geräte-URL):
webhooks:
- url: "https://ntfy.sh/my-gpu-topic" # 手机装 ntfy 订阅同一 topic
kind: ntfy
min_severity: warning # info|warning|critical，低于此不推
# types: ["OOM", "LOSS_NAN"] # 可选：只推这些事件类型Lokale Automatisierung (bei Ereigniseingang einen Befehl auf dem Gerät ausführen, z.B. einen lokalen Agenten aus dem Standby —):
gpuctl event-hook --severity critical -- /path/to/on-event.sh
# 事件经 GPUCTL_EVENT_TYPE/SEVERITY/MESSAGE/RUN_ID/... 环境变量 + stdin JSON 传入gpuctl-mcp ist ein eigenständiger Adapter-Prozess (unabhängig von server/agent) und exponiert die Kontrollellebene als 21 MCP-Werkzeuge. Nach Konfiguration steuert Claude Code (oder ein beliebiger MCP-Client) den Ablauf „Submit training → over monitor anomalies → compare Checkpoints → recommendation“ allein über natürliche Sprache – ohne Web/CLI zu nutzen:
# 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"Lese/Schreib-Schutz: Mit einem read-only Token geben submit_job/cancel_job/retry_job/evaluate_checkpoint/set_primary_metric einen WriteScopeError zurück.
Die drei Skills (.claude/skills/gpu-training/) kodieren den Experiment-Zyklus und autorisieren MCP-Werkzeuge; siehe 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()In einem via Plattform gestarteten Job ist keinerlei Konfiguration nötig (Env-, Injektion automatisch). Ein außerhalb der Plattform (bare run) wird automatisch als Run mit source=sdk registriert; ohne Server wird still auf einen lokalen jsonl (~/.gpuctl/spool/) zurückgegriffen, das Trainingsskript bleibt unverändert.
┌────────────┐ 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 ist ein unabhängiger Adapter-Prozess und benötigt weder server noch 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 ist ein optional; der Process-Runner bleibt Standard. Vor der Verwendung von GPU-Containern muss auf dem Agent-Host das NVIDIA Container Toolkit installiert und die Runtime in die Docker-Konfiguration aufgenommen werden:
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker # 先确认没有运行中的容器
docker run --rm --gpus all <cuda-image> nvidia-smiUnterWSL2 sollte zuerst die Host-Stotzübergabe geprüft werden (GPU in nvidia-smi sichtbar); das Container Toolkit setzt lediglich die bereits durchgereichte GPU im Container um—kein Ersatz für den Windows/WSL-Treibz.
Keepensshofr? Ne, "Trainingscode bleibt Plattform-unabhängig": python train.py muss jederzeit innerhalb und außerhalb des Systems laufen.
Telemetrie im Best-Effort-Eindeutig: Berichte, die einmal scheitern, werden nur lokal auf warten und werfen dem Trainingsprozess niemals einen Fehler zu.
Requirements mit bestehenden Prozessen (Prozess-Runner ist erste Klasse); Docker/Git werden nicht erzwungen.
GPU-Scheduling strikt Slot-basis; Flexierung niemals über die GPU-Auslastung definiert.
Job ≠ Run: Job ist die Scheduling-Einheit, Run ist die Training-SM-Einheit (ein Run pro Start-Versuch).
SQLite und keine Message-Queue; Server als Ein-Worker-Operation, das In-Memory-Pub/Sub ist bewusst gehalten.
GPUPlane steht unter der Apache License 2.0. Weitere Angaben: 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.
