camilbenameur/remote-devbox

Was macht remote-devbox?

Du richtest eine Devbox ein (oder reparierst sie): einen Linux-Server, auf dem Claude-Code-Sitzungen ausgeführt werden, während die Claude-Desktop-App auf dem Rechner des Benutzers nur die Benutzeroberfläche ist. Arbeite die Phasen der Reihe nach durch. Jede Phase sagt, was du tust, was nur der Benutzer tun kann und wie du überprüfst, ob es funktioniert hat.

<skill> unten bezeichnet den Ordner, der diese Datei enthält.

Was der Benutzer bekommt

• Die Registerkarte Code der Desktop-App, unverändert, wobei jede Sitzung auf der Devbox per SSH läuft: Shell, Tests, Installationen, Python, Node, Chrome. Der Computer zeichnet nur die Oberfläche.
• Das Abonnement des Benutzers, keine API-Guthaben. Die Desktop-App übergibt und erneuert die Anmeldung der Sitzung. Setze niemals ANTHROPIC_API_KEY auf der Devbox: Die Abrechnung würde auf die API wechseln.
• Zwei Browser als MCP-Server: chrome, ein gemeinsamer Chrome, der in den Benutzerkonten angemeldet ist, und playwright, ein leerer, isolierter Chrome pro Sitzung. Ein virtueller Bildschirm zeigt den gemeinsamen Chrome in einem beliebigen Webbrowser im privaten Netzwerk des Benutzers (noVNC).
• Sitzungen, die bei ausgeschaltetem Computer weiterlaufen: devbox-relay setzt abgebrochene Desktop-Sitzungen im Hintergrund fort, und devbox-rc hostet Sitzungen, die von claude.ai/code oder der Telefon-App gestartet wurden.
• Dieselbe globale CLAUDE.md, Skills, Speicher und Plugin-Hooks wie auf dem Computer.

Lies references/how-it-works.md, wenn du die Mechanismen brauchst, und references/troubleshooting.md, sobald etwas fehlschlägt.

Grundregeln für dich

• Der Benutzer erledigt: Zahlung und Bestellung, jedes Passwort und jede Anmeldung (Anbieter, Tailscale, GitHub-Gerätecode, Claude /login, die Websites im gemeinsamen Chrome), Klicks in den Einstellungen der Desktop-App sowie die Tailscale-Admin-Konsole. Gib ihnen den genauen Link oder Befehl, einen nach dem anderen, und warte dann. Gib niemals ein Passwort, eine Kreditkartennummer oder einen Einmalcode selbst ein.
• Bevor du etwas bestellst, nenne den Plan, den Preis und die Verbindlichkeit und hole ein Ja ein.
• Die Setup-Skripte sind idempotent: Wenn eines fehlschlägt, lies den Fehler, behebe die Ursache, führe es erneut aus.
• Auf der Devbox benötigt sudo kein Passwort. Frage den Benutzer dennoch vor jeder Systemänderung, die die Skripte nicht selbst vornehmen (Pakete, Dienste, Firewall, sshd, Benutzer).
• Wenn du an der Live-Devbox des Benutzers arbeitest, stoppe niemals devbox-*-Dienste, bearbeite ~/.claude oder ersetze Binärdateien in ~/.local/bin, ohne dies vorher zu sagen: Ihre Sitzungen laufen möglicherweise.

Phase 0: Computer prüfen

1. Plattform. Windows: Skripte in <skill>/client/windows/ (Windows PowerShell 5.1 ist in Ordnung). macOS oder Linux: <skill>/client/unix/.
2. Nur Windows: OpenSSH-Client 9.4 oder neuer (ssh -V). Die Desktop-App benötigt ihn. Bei älterer Version: winget install Microsoft.OpenSSH.Preview.
3. Die Claude-Desktop-App ist installiert und angemeldet, und der Plan des Benutzers beinhaltet Claude Code.
4. git config --global user.name und user.email sind gesetzt (die Skripte kopieren sie auf die Devbox).
5. Frage den Benutzer, welche optionalen Teile er möchte: Gatehaul (führt schwere Builds in GitHub Codespaces aus, -Gatehaul / --gatehaul), den gemeinsamen eingeloggten Chrome (standardmäßig aktiviert), Speicherkopie.

Phase 1: Server auswählen und bestellen

Verwende references/providers.md. Anforderungen: KVM-Virtuelle Maschine, Ubuntu 24.04, x86_64 bevorzugt (arm64 funktioniert, ist aber nicht Ende-zu-Ende getestet), mindestens 8 GB RAM (16 bis 24 GB für mehrere parallele Sitzungen plus Chrome), 80 GB Festplatte und eine Web-Konsole vom Anbieter (sie ist der Rettungsweg, falls SSH jemals gesperrt ist).

Hilf dem Benutzer beim Vergleichen, öffne dann die Bestellseite für ihn, wenn du einen Browser hast. Der Benutzer wählt den Tarif, bezahlt und bestätigt. Wenn der Anbieter bei der Bestellung einen SSH-Key verlangt, zeige ihn zuerst an:

powershell -ExecutionPolicy Bypass -File <skill>\client\windows\setup-devbox.ps1 -ShowKey

bash <skill>/client/unix/setup-devbox.sh --show-key

Frage den Benutzer nach der öffentlichen IP und dem initialen Benutzer (oft root; ubuntu bei OVH und Oracle).

Phase 2: Server bootstrappen

powershell -ExecutionPolicy Bypass -File <skill>\client\windows\setup-devbox.ps1 -HostAddress <IP> -InitialUser root

bash <skill>/client/unix/setup-devbox.sh --host <IP> --initial-user root

Führe es in einem Terminal aus, in das der Benutzer tippen kann (das Terminal-Panel der Desktop-App oder bitte ihn, es auszuführen). Es benötigt drei Dinge vom Benutzer:

1. Host-Key-Fingerprint. Das Skript zeigt ihn an und fragt ja/nein. Sage dem Benutzer, er solle ihn mit der Ausgabe des Web-Konsolen-Befehls des Anbieters ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub vergleichen.
2. Initiales Passwort, einmalig, damit der Key autorisiert werden kann (übersprungen, wenn der Key bei der Bestellung angegeben wurde).
3. GitHub-Gerätecode: gh auth login gibt einen Code und einen Link aus.

Was es macht: Erstellt den Key ~/.ssh/devbox_ed25519 (keine Passphrase, die Desktop-App muss ohne Eingabeaufforderung verbinden), führt host/10-root-bootstrap.sh aus (Dev-Benutzer mit sudo, Key-only-SSH, Linger, Swap, Node, gh, Chrome, Tailscale, ufw, fail2ban, unattended upgrades, Pakete für virtuellen Bildschirm), fügt den Host devbox-Block zu ~/.ssh/config hinzu, testet ihn, schränkt SSH auf den Dev-Benutzer ein, führt host/20-user-setup.sh aus (uv, Claude Code CLI, optionales Gatehaul, MCP-Server, ~/.local/bin-Tools, Dienste für virtuellen Bildschirm, Relay-Dienst und Hook), synchronisiert dann die Claude-Konfiguration (Phase 6).

Prüfung: ssh devbox 'claude --version; claude mcp list; systemctl --user is-active devbox-vnc devbox-chrome devbox-relay'.

Phase 3: Privates Netzwerk, dann öffentliches SSH schließen

1. Benutzer: Tailscale auf dem Computer installieren und anmelden (winget install tailscale.tailscale, der Mac App Store oder tailscale.com/download).
2. Auf der Devbox: ssh -t devbox sudo tailscale up --hostname=devbox. Es gibt einen Anmeldelink aus: Der Benutzer öffnet ihn.
3. Benutzer: Tailscale-Admin-Konsole, Machines, devbox, Disable key expiry. Sonst verlässt die Devbox das Netzwerk nach 180 Tagen und nur die Anbieterkonsole bleibt.
4. Setze in ~/.ssh/config den HostName des devbox-Blocks auf devbox (MagicDNS) oder auf die Adresse von ssh devbox tailscale ip -4. Prüfe ssh devbox true.
5. Öffentliches SSH schließen: ssh -t devbox 'bash ~/devbox-setup/30-root-lockdown.sh'. Es verweigert, solange eine SSH-Sitzung geöffnet ist, die nicht über Tailscale hereinkommt: Schließe diese zuerst (einschließlich Desktop-App-Sitzungen, die über die öffentliche IP geöffnet wurden).

Rettung bei Aussperrung: Anbieter-Web-Konsole, dann sudo ufw allow OpenSSH.

Phase 4: Desktop-App verbinden

Der Benutzer in der Desktop-App: Registerkarte Code, Umgebungsmenü unter dem Eingabefeld, New environment, SSH (Bezeichnungen Stand Ende 2026, sie können sich ändern):

Feld	Wert
SSH host	devbox (aus ~/.ssh/config)
SSH key	leer
Worktree folder	~/worktrees
Folder for a session	~/dev/<project>

Bei der ersten Verbindung installiert die App ihre eigene Engine unter ~/.claude/remote/ auf der Devbox und zeigt den Host-Key an: derselbe Fingerabdruck wie in Phase 2. Sitzungen in dieser Umgebung laufen auf der Devbox. In SSH-Sitzungen gibt es keinen Browser-Bereich: Leite stattdessen Ports weiter (siehe Tägliche Nutzung).

Phase 5: Der eingeloggte Chrome

1. ssh devbox devbox-browser login (Chrome startet ohne seinen Debugging-Port neu, weil Google die Anmeldung in einem Chrome, der einen solchen Port hat, oft verweigert).
2. Der Benutzer öffnet http://devbox:6080/vnc.html von einem Rechner im Tailnet. Passwort: ssh devbox devbox-browser password. Ohne Tailscale: ssh -N -L 6080:localhost:6080 devbox und http://localhost:6080/vnc.html.
3. Der Benutzer meldet sich auf den Websites an, die Agenten verwenden sollen. Rate von Banking und allem ab, bei dem eine eingeschleuste Anweisung Geld kosten könnte: Jede Sitzung kann diesen Browser steuern.
4. ssh devbox devbox-browser normal übergibt ihn zurück an die Agenten (Debugging-Port 9222, nur lokal).

Prüfung: Bitte in einer Devbox-Sitzung den chrome-MCP, eine Website zu öffnen, auf der der Benutzer angemeldet ist, und bestätige, dass das Konto sichtbar ist, ohne private Inhalte zu lesen. Das Taskleistensymbol und das Rechtsklickmenü des Bildschirms öffnen diesen Chrome; er ist auch der Standardbrowser der Devbox.

Phase 6: Die lokale Claude-Umgebung spiegeln

Ziel: Eine Sitzung auf der Devbox verhält sich wie eine auf dem Computer.

1. Globale CLAUDE.md und Skills:

   powershell -ExecutionPolicy Bypass -File <skill>\client\windows\sync-claude-config.ps1 -Memory
   

   bash <skill>/client/unix/sync-claude-config.sh --memory
   

   Es stellt <skill>/templates/host-header.md (was auf der Devbox anders ist: Pfade, Browser, Bildschirm, Kontinuität, sudo-Regel) vor die lokale ~/.claude/CLAUDE.md, führt ~/.claude/skills zusammen (ohne .venv, node_modules, .git) und kopiert mit -Memory den Auto-Speicher des lokalen Projekte-Ordners (-LocalDevDir, Standard ~/Documents/dev) in den Speicher von ~/dev auf der Devbox. Führe es erneut aus, wenn sich die lokale CLAUDE.md oder die Skills ändern. Bearbeite die Header-Vorlage, nicht die Kopie auf der Devbox, die überschrieben wird.
2. Skills, die Einrichtung benötigen: Suche für jeden synchronisierten Skill nach Python-Umgebungen (requirements.txt, pyproject.toml), Node-Paketen, Binärdateien und Windows-Pfaden in SKILL.md. Erstelle Umgebungen auf der Devbox neu und korrigiere Pfade. Installiere benötigte Systemtools (z. B. ffmpeg) nach Rückfrage.
3. Plugins: Die Desktop-App installiert die Plugins des Benutzers in SSH-Sitzungen, aber ihre Hooks laufen dort nicht. Klone für jedes aktivierte Plugin mit hooks/hooks.json seine Quelle auf der Devbox im selben Commit in ~/.claude/hooks-thirdparty/<plugin> und führe seine Hooks in ~/.claude/settings.json der Devbox zusammen, wobei ${CLAUDE_PLUGIN_ROOT} durch diesen Ordner ersetzt und Interpreter für Linux korrigiert werden (python zu python3). Führe mit jq zusammen; behalte den vorhandenen devbox-relay guard SessionStart-Hook. Lies Hook-Skripte, bevor du sie aktivierst.
4. MCP-Server: Vergleiche claude mcp list lokal und auf der Devbox. Füge benutzerweite Stdio-Server hinzu, die auf Linux Sinn ergeben. claude.ai-Connectors folgen dem Konto: nichts zu tun.
5. Projekte: Klone mit gh repo clone in ~/dev/<name>. Kopiere nicht committete oder ignorierte lokale Dateien, die wichtig sind (.env-Dateien nur mit Zustimmung des Benutzers), installiere Abhängigkeiten, führe einen leichten Test aus. Schwere Builds gehören in Codespaces via Gatehaul, falls installiert.
6. Lange Migration ohne den Benutzer: Wenn viel zu übertragen ist, schreibe eine Arbeitsliste, starte dann eine autonome Sitzung auf der Devbox mit references/setup-agent-prompt.md über claude-task.

Phase 7: Sitzungen, die bei ausgeschaltetem Computer weiterlaufen

1. CLI-Anmeldung auf der Devbox (das Relay und die Remote Control verwenden sie): ssh -t devbox claude, dann /login; der Benutzer öffnet den Link und fügt den Code ein; /exit.
2. Relay: Bereits durch 20-user-setup.sh aktiviert. Prüfe ssh devbox devbox-relay test (alle Fälle OK) und ssh devbox devbox-relay status.
3. Remote Control Server, einmalig von Hand, weil er zwei Bestätigungen verlangt: ssh -t devbox 'cd ~/dev && claude remote-control', der Benutzer antwortet zweimal mit y, dann Strg+C. Dann ssh devbox 'touch ~/.config/devbox/rc-accepted && systemctl --user enable --now devbox-rc'. In claude.ai/code oder der Telefon-App startet die Umgebung, die nach dem Ordner und dem Host benannt ist (z. B. dev · <Hostname>), nun Sitzungen auf der Devbox. Wähle dort den Auto-Berechtigungsmodus für Sitzungen, die allein voranschreiten sollen. claude.ai fordert den Benutzer möglicherweise auf, sich erneut anzumelden, um das Gerät zu verifizieren.
4. Optionaler echter Test mit dem Benutzer: Starte eine kleine Aufgabe in einer Desktop-Sitzung, die bei einer Berechtigungsfrage stoppt, der Benutzer schließt die Desktop-App, wartet etwa 30 Minuten, öffnet sie erneut; das Log ~/dev/_relay/log.md zeigt das Relay, claude agents auf der Devbox zeigt relay · <name>, und die wieder geöffnete ursprüngliche Sitzung sagt, dass sie weitergeleitet wurde.

Phase 8: Abschlussprüfung

Führe jede Zeile aus und berichte:

ssh devbox 'claude --version; gh auth status 2>&1 | head -3; claude mcp list'
ssh devbox 'systemctl --user is-active devbox-vnc devbox-wm devbox-novnc devbox-panel devbox-chrome devbox-relay devbox-rc'
ssh devbox 'devbox-browser status; devbox-relay test | tail -1; free -h; df -h ~'
ssh devbox 'grep -c ANTHROPIC_API_KEY ~/.bashrc ~/.profile 2>/dev/null; sudo ufw status'

Erwartet: Jeder Dienst active (devbox-rc erst nach Phase 7), MCP-Server chrome und playwright verbunden, kein API-Key, ufw erlaubt nur tailscale0 (und 41641/udp). Teile dem Benutzer dann mit, was bereit ist, was er noch tun muss und wie er auf jeden Teil zugreift.

Tägliche Nutzung (dem Benutzer mitteilen)

• Einen Dev-Server sehen: Führe ihn auf 127.0.0.1:<port> auf der Devbox aus, dann auf dem Computer ssh -N -L <port>:localhost:<port> devbox und öffne http://localhost:<port>.
• Lange Aufgabe in tmux: claude-task start <name> ~/dev/<project> "<prompt>" [--rc] [--mode auto], dann claude-task list | show | send | stop; tmux attach -t ct-<name> (Strg+B d zum Verlassen).
• Eine Sitzung absichtlich in den Hintergrund geben: claude --resume <id> --fork-session --bg --remote-control "<name>" --permission-mode auto "<prompt>".
• Relay-Aktivität: ssh devbox devbox-relay status, Log in ~/dev/_relay/log.md.
• Tools aktualisieren: PW_MCP_VERSION=<v> INSTALL_GATEHAUL=1 GATEHAUL_VERSION=<tag> bash ~/devbox-setup/20-user-setup.sh.
• Ein ausgeschalteter Server wird normalerweise weiter berechnet.