1. Typische Stolpersteine
Unklare Prerequisites, falsches Prozessmodell, zu wenig Observability — wiederholen sich unabhängig vom Feature-Release-Zyklus.
2. Checkliste vor dem Start
| Punkt | Hinweis | Risiko |
|---|---|---|
| Node | Dokumentation einhalten | Native/CLI-Mismatch |
| Paketmanager | Pro Repo festlegen | Lockfile-Drift |
| Pfade | Tatsächlich gelesene Dateien prüfen | Leere Edits |
| API-Keys | Least privilege | Kosten/Leaks |
3. Onboard-Zweck
Schlüssel, Kanal, Laufzeitmodus und Workspace zusammenführen. Bei Fehlern Stacktrace und Schrittnummer sichern.
4. Vordergrund vs. Daemon
Erst stdout sichtbar machen, dann mit gleichem Health-Check zum Daemon promovieren; WorkingDirectory und ENV explizit setzen.
5. Fünf Schritte Smoke
Listen/Health → minimale Nachricht → Log-Labels → Proxy/TLS → Version und Request-ID dokumentieren.
6. Ports & Logs
| Symptom | Zuerst | Maßnahme |
|---|---|---|
| Port belegt | lsof | Prozess beenden/Port wechseln |
| Daemon stirbt sofort | Service-Logs | Im Vordergrund reproduzieren |
| Stiller Kanal | Webhook/Firewall | curl innen/außen |
| Flaky | Sleep/Throttling | Energieeinstellungen, Backoff |
Betrieb:
- Logs in zusammenhängenden Blöcken lesen.
- Vor/nach Minor-Upgrades Health+E2E.
- Remote-Mac: freier Speicher und Rotation (DSGVO-Prozesse beachten).
7. Dauerbetrieb auf Remote-Mac
Sleep-Richtlinien, Neustart nach OS-Updates, Log-Rotation, konsistenter Dienstbenutzer — als kurzes Runbook.
8. Reproduzierbare Boot-Pfade
Versionierte Onboard-Artefakte schlagen lange Feature-Listen. Gateway auf dediziertem Remote-Mac entkoppelt GPU/Rendering-Last von der Agent-Schicht.
MACGPU Remote-Macs bieten durchgängige Stromversorgung und klarere Ressourcengrenzen; stundenweise Abrechnung für Piloten.