camilbenameur/remote-devbox

Que fait remote-devbox ?

Vous êtes en train de configurer (ou de réparer) un devbox : un serveur Linux où les sessions Claude Code s'exécutent pendant que l'application de bureau Claude sur l'ordinateur de l'utilisateur n'est que l'interface. Suivez les phases dans l'ordre. Chaque phase indique ce que vous faites, ce que seul l'utilisateur peut faire, et comment vérifier que cela a fonctionné.

<skill> ci-dessous désigne le dossier qui contient ce fichier.

Ce que l'utilisateur obtient

• L'onglet Code de l'application de bureau, inchangé, avec chaque session s'exécutant sur le devbox via SSH : shell, tests, installations, Python, Node, Chrome. L'ordinateur ne dessine que l'interface.
• L'abonnement de l'utilisateur, pas les crédits API. L'application de bureau transmet et rafraîchit la connexion de la session. Ne définissez jamais ANTHROPIC_API_KEY sur le devbox : la facturation passerait à l'API.
• Deux navigateurs en tant que serveurs MCP : chrome, un seul Chrome partagé connecté aux comptes de l'utilisateur, et playwright, un Chrome isolé vierge par session. Un écran virtuel affiche le Chrome partagé dans n'importe quel navigateur web sur le réseau privé de l'utilisateur (noVNC).
• Des sessions qui continuent même lorsque l'ordinateur est éteint : devbox-relay reprend les sessions Desktop coupées en arrière-plan, et devbox-rc héberge les sessions démarrées depuis claude.ai/code ou l'application téléphone.
• Le même CLAUDE.md, les mêmes skills, la même mémoire et les mêmes hooks de plugins que sur l'ordinateur.

Consultez references/how-it-works.md lorsque vous avez besoin des mécanismes, et references/troubleshooting.md dès que quelque chose échoue.

Règles de base pour vous

• L'utilisateur fait : le paiement et la commande, tous les mots de passe et connexions (fournisseur, Tailscale, code d'appareil GitHub, Claude /login, les sites web dans le Chrome partagé), les clics dans les paramètres de l'application de bureau, et la console d'administration Tailscale. Donnez-leur le lien ou la commande exacte, un par un, puis attendez. Ne tapez jamais vous-même un mot de passe, un numéro de carte ou un code à usage unique.
• Avant de commander quoi que ce soit, énoncez le plan, le prix et l'engagement, et obtenez un oui.
• Les scripts de configuration sont idempotents : quand l'un échoue, lisez l'erreur, corrigez la cause, exécutez-le à nouveau.
• Sur le devbox, sudo ne nécessite pas de mot de passe. Demandez toujours à l'utilisateur avant toute modification système que les scripts n'effectuent pas eux-mêmes (paquets, services, pare-feu, sshd, utilisateurs).
• Lorsque vous travaillez sur le devbox en direct de l'utilisateur, n'arrêtez jamais les services devbox-*, ne modifiez pas ~/.claude et ne remplacez pas les binaires dans ~/.local/bin sans le dire d'abord : leurs sessions peuvent être en cours d'exécution.

Phase 0 : vérifier l'ordinateur

1. Plateforme. Windows : scripts dans <skill>/client/windows/ (Windows PowerShell 5.1 convient). macOS ou Linux : <skill>/client/unix/.
2. Windows uniquement : client OpenSSH 9.4 ou plus récent (ssh -V). L'application de bureau en a besoin. Si plus ancien : winget install Microsoft.OpenSSH.Preview.
3. L'application de bureau Claude est installée et connectée, et le plan de l'utilisateur inclut Claude Code.
4. git config --global user.name et user.email sont définis (les scripts les copient sur le devbox).
5. Demandez à l'utilisateur quelles parties optionnelles il souhaite : gatehaul (exécute les builds lourds dans GitHub Codespaces, -Gatehaul / --gatehaul), le Chrome partagé connecté (activé par défaut), la copie de la mémoire.

Phase 1 : choisir et commander un serveur

Utilisez references/providers.md. Exigences : machine virtuelle KVM, Ubuntu 24.04, x86_64 de préférence (arm64 fonctionne mais n'est pas testé de bout en bout), 8 Go de RAM au strict minimum (16 à 24 Go pour plusieurs sessions parallèles plus Chrome), 80 Go de disque, et une console web du fournisseur (c'est le chemin de secours si SSH est jamais verrouillé).

Aidez l'utilisateur à comparer, puis ouvrez la page de commande pour lui si vous avez un navigateur. L'utilisateur choisit le plan, paie et confirme. Si le fournisseur demande une clé SSH au moment de la commande, affichez-la d'abord :

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

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

Demandez à l'utilisateur l'IP publique et l'utilisateur initial (souvent root ; ubuntu chez OVH et Oracle).

Phase 2 : amorcer le serveur

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

Exécutez-le dans un terminal dans lequel l'utilisateur peut taper (le panneau du terminal de l'application de bureau, ou demandez-lui de l'exécuter). Il a besoin de trois choses de la part de l'utilisateur :

1. Empreinte de la clé d'hôte. Le script l'affiche et demande oui/non. Dites à l'utilisateur de la comparer avec la sortie de la console web du fournisseur de ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub.
2. Mot de passe initial, une fois, pour que la clé puisse être autorisée (ignoré si la clé a été donnée à la commande).
3. Code d'appareil GitHub : gh auth login affiche un code et un lien.

Ce qu'il fait : crée la clé ~/.ssh/devbox_ed25519 (sans phrase de passe, l'application de bureau doit se connecter sans invite), exécute host/10-root-bootstrap.sh (utilisateur dev avec sudo, SSH par clé uniquement, linger, swap, Node, gh, Chrome, Tailscale, ufw, fail2ban, mises à niveau automatiques, paquets d'écran virtuel), ajoute le bloc Host devbox à ~/.ssh/config, le teste, restreint SSH à l'utilisateur dev, exécute host/20-user-setup.sh (uv, CLI Claude Code, gatehaul optionnel, serveurs MCP, outils ~/.local/bin, services d'écran virtuel, service de relais et hook), puis synchronise la configuration Claude (Phase 6).

Vérification : ssh devbox 'claude --version; claude mcp list; systemctl --user is-active devbox-vnc devbox-chrome devbox-relay'.

Phase 3 : réseau privé, puis fermeture du SSH public

1. Utilisateur : installez Tailscale sur l'ordinateur et connectez-vous (winget install tailscale.tailscale, le Mac App Store, ou tailscale.com/download).
2. Sur le devbox : ssh -t devbox sudo tailscale up --hostname=devbox. Cela affiche un lien de connexion : l'utilisateur l'ouvre.
3. Utilisateur : console d'administration Tailscale, Machines, devbox, Désactiver l'expiration de la clé. Sinon, le devbox quitte le réseau après 180 jours et il ne reste que la console du fournisseur.
4. Dans ~/.ssh/config, définissez le HostName du bloc devbox sur devbox (MagicDNS) ou sur l'adresse de ssh devbox tailscale ip -4. Vérifiez ssh devbox true.
5. Fermez le SSH public : ssh -t devbox 'bash ~/devbox-setup/30-root-lockdown.sh'. Il refuse tant qu'une session SSH qui ne passe pas par Tailscale est ouverte : fermez d'abord celles-ci (y compris les sessions de l'application de bureau ouvertes sur l'IP publique).

Secours en cas de verrouillage : console web du fournisseur, puis sudo ufw allow OpenSSH.

Phase 4 : connecter l'application de bureau

L'utilisateur, dans l'application de bureau : onglet Code, menu d'environnement sous la boîte d'invite, Nouvel environnement, SSH (les libellés peuvent changer d'ici fin 2026) :

Champ	Valeur
Hôte SSH	devbox (tiré de ~/.ssh/config)
Clé SSH	vide
Dossier de travail	~/worktrees
Dossier pour une session	~/dev/<projet>

Lors de la première connexion, l'application installe son propre moteur dans ~/.claude/remote/ sur le devbox et affiche la clé d'hôte : même empreinte qu'à la Phase 2. Les sessions dans cet environnement s'exécutent sur le devbox. Il n'y a pas de panneau Navigateur dans les sessions SSH : transférez les ports à la place (voir Utilisation quotidienne).

Phase 5 : le Chrome connecté

1. ssh devbox devbox-browser login (Chrome redémarre sans son port de débogage, car Google refuse souvent la connexion dans un Chrome qui en a un).
2. L'utilisateur ouvre http://devbox:6080/vnc.html depuis une machine sur le tailnet. Mot de passe : ssh devbox devbox-browser password. Sans Tailscale : ssh -N -L 6080:localhost:6080 devbox et http://localhost:6080/vnc.html.
3. L'utilisateur se connecte aux sites que les agents doivent utiliser. Déconseillez les opérations bancaires et tout ce où une instruction injectée pourrait coûter de l'argent : chaque session peut piloter ce navigateur.
4. ssh devbox devbox-browser normal le rend aux agents (port de débogage 9222, local uniquement).

Vérification : dans une session devbox, demandez au MCP chrome d'ouvrir un site sur lequel l'utilisateur est connecté et confirmez que le compte est visible, sans lire de contenu privé. L'icône de la barre des tâches et le menu contextuel de l'écran ouvrent ce Chrome ; c'est aussi le navigateur par défaut du devbox.

Phase 6 : refléter l'environnement Claude local

Objectif : une session sur le devbox se comporte comme sur l'ordinateur.

1. CLAUDE.md et skills globaux :

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

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

   Il préfixe <skill>/templates/host-header.md (ce qui diffère sur le devbox : chemins, navigateurs, écran, continuité, règle sudo) au ~/.claude/CLAUDE.md local, fusionne ~/.claude/skills (sans .venv, node_modules, .git), et avec -Memory copie l'auto-mémoire du dossier de projets local (-LocalDevDir, par défaut ~/Documents/dev) vers la mémoire de ~/dev sur le devbox. Réexécutez-le à chaque modification du CLAUDE.md ou des skills locaux. Modifiez le modèle d'en-tête, pas la copie sur le devbox, qui est écrasée.
2. Skills nécessitant une configuration : pour chaque skill synchronisé, recherchez les environnements Python (requirements.txt, pyproject.toml), les paquets Node, les binaires et les chemins Windows dans SKILL.md. Recréez les environnements sur le devbox et corrigez les chemins. Installez les outils système dont ils ont besoin (par exemple ffmpeg) après avoir demandé.
3. Plugins : l'application de bureau installe les plugins de l'utilisateur dans les sessions SSH, mais leurs hooks ne s'y exécutent pas. Pour chaque plugin activé avec hooks/hooks.json, clonez sa source sur le devbox au même commit dans ~/.claude/hooks-thirdparty/<plugin>, et fusionnez ses hooks dans le ~/.claude/settings.json du devbox, avec ${CLAUDE_PLUGIN_ROOT} remplacé par ce dossier et les interpréteurs corrigés pour Linux (python en python3). Fusionnez avec jq ; conservez le hook SessionStart devbox-relay guard existant. Lisez les scripts de hook avant de les activer.
4. Serveurs MCP : comparez claude mcp list localement et sur le devbox. Réajoutez les serveurs stdio de scope utilisateur qui ont du sens sur Linux. Les connecteurs claude.ai suivent le compte : rien à faire.
5. Projets : clonez dans ~/dev/<nom> avec gh repo clone. Copiez les fichiers locaux non commités ou ignorés qui comptent (fichiers .env uniquement avec le consentement de l'utilisateur), installez les dépendances, exécutez un test léger. Les builds lourds appartiennent à Codespaces via gatehaul s'il est installé.
6. Migration longue sans l'utilisateur : s'il y a beaucoup à déplacer, écrivez une liste de travail, puis démarrez une session autonome sur le devbox avec references/setup-agent-prompt.md via claude-task.

Phase 7 : sessions qui continuent avec l'ordinateur éteint

1. Connexion CLI sur le devbox (le relais et le contrôle à distance l'utilisent) : ssh -t devbox claude, puis /login ; l'utilisateur ouvre le lien et colle le code ; /exit.
2. Relais : déjà activé par 20-user-setup.sh. Vérifiez ssh devbox devbox-relay test (tous les cas OK) et ssh devbox devbox-relay status.
3. Serveur de contrôle à distance, une fois à la main car il demande deux confirmations : ssh -t devbox 'cd ~/dev && claude remote-control', l'utilisateur répond y deux fois, puis Ctrl+C. Ensuite ssh devbox 'touch ~/.config/devbox/rc-accepted && systemctl --user enable --now devbox-rc'. Dans claude.ai/code ou l'application téléphone, l'environnement nommé d'après le dossier et l'hôte (par exemple dev · <hostname>) démarre maintenant des sessions sur le devbox. Choisissez le mode d'autorisation Auto là-bas pour les sessions qui doivent progresser seules. claude.ai peut demander à l'utilisateur de se reconnecter pour vérifier l'appareil.
4. Test réel optionnel, avec l'utilisateur : démarrez une petite tâche dans une session Desktop qui s'arrêtera sur une question d'autorisation, l'utilisateur quitte l'application de bureau, attend environ 30 minutes, la rouvre ; le fichier ~/dev/_relay/log.md montre le relais, claude agents sur le devbox montre relay · <nom>, et la session originale rouverte indique qu'elle a été relayée.

Phase 8 : vérification finale

Exécutez et rapportez chaque ligne :

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'

Résultat attendu : chaque service active (devbox-rc seulement après la Phase 7), serveurs MCP chrome et playwright connectés, pas de clé API, ufw autorisant uniquement tailscale0 (et 41641/udp). Ensuite, dites à l'utilisateur ce qui est prêt, ce qu'il lui reste à faire, et comment accéder à chaque partie.

Utilisation quotidienne (à dire à l'utilisateur)

• Voir un serveur de dev : exécutez-le sur 127.0.0.1:<port> sur le devbox, puis sur l'ordinateur ssh -N -L <port>:localhost:<port> devbox et ouvrez http://localhost:<port>.
• Tâche longue dans tmux : claude-task start <nom> ~/dev/<projet> "<prompt>" [--rc] [--mode auto], puis claude-task list | show | send | stop ; tmux attach -t ct-<nom> (Ctrl+b d pour quitter).
• Passer volontairement une session en arrière-plan : claude --resume <id> --fork-session --bg --remote-control "<nom>" --permission-mode auto "<prompt>".
• Activité du relais : ssh devbox devbox-relay status, log dans ~/dev/_relay/log.md.
• Mettre à jour les outils : PW_MCP_VERSION=<v> INSTALL_GATEHAUL=1 GATEHAUL_VERSION=<tag> bash ~/devbox-setup/20-user-setup.sh.
• Un serveur éteint est généralement toujours facturé.