Configurer une Machine Distante pour le Codage Agentique

La pile minimale pour exécuter Claude Code sur une machine distante comprend un VPS Linux ou une machine toujours en ligne, Tailscale pour un mesh WireGuard privé ne nécessitant ni redirection de port ni DNS dynamique, tmux pour des sessions de terminal persistantes survivant aux déconnexions, et mosh ou SSH comme couche de connexion — le tout gratuit, composable, et pérenne au-delà des outils d’encapsulation du moment. Ce guide parcourt cette pile de bout en bout pour le cas courant que les tutoriels existants ignorent : un agent de codage sur un VPS cloud ou une machine de rechange, sécurisé et piloté à distance depuis un ordinateur portable ou un téléphone.

Le problème à résoudre est celui de la persistance. Lorsque vous exécutez un agent de codage localement et fermez votre ordinateur portable, la session meurt. Une machine distante maintient l’agent actif entre les déconnexions, vous offre la maîtrise et un coût prévisible par rapport à une plateforme gérée, et vous permet de superviser le travail depuis n’importe où. L’inconvénient — peu documenté — est qu’une machine faisant tourner un agent avec accès au shell et des clés API constitue une surface d’attaque sérieuse ; c’est pourquoi ce guide aborde la sécurité en premier plutôt que de la traiter comme un ajout tardif.

Pourquoi une Machine Distante, et DIY vs. les Alternatives

Une machine distante s’impose lorsque vous avez besoin d’un agent de codage qui survit aux déconnexions, s’exécute sans surveillance et reste accessible depuis n’importe quel appareil — sans payer la redevance par utilisateur d’une plateforme ni accepter ses limitations de bac à sable. La contrepartie est opérationnelle : vous êtes responsable de la sécurité, de la disponibilité et des mises à jour. Pour les développeurs déjà à l’aise avec SSH et Git, cet échange en vaut généralement la peine.

Avant de construire quoi que ce soit, déterminez laquelle des trois approches vous convient. Le paysage a évolué début 2026, et l’ancienne formulation « vous avez besoin de tmux et SSH pour utiliser Claude Code à distance » est désormais incomplète.

Anthropic a livré le Remote Control natif en avant-première de recherche et les Remote Sessions cloud début 2026 (CLI v2.1.x à mi-2026). Remote Control utilise le HTTPS sortant uniquement — sans ports entrants — pour vous permettre de piloter une session depuis votre téléphone. C’est genuinement utile, mais c’est mono-session et cela s’arrête avec le terminal qui l’a lancé. Claude Code lui-même s’exécute comme un outil CLI sans démon en arrière-plan pour les sessions interactives ; la demande de fonctionnalité ouverte pour un mode démon sans interface confirme que fermer le terminal met fin à la session. Pour les configurations toujours actives, sans interface ou multi-projets, vous vous appuyez sur des primitives durables sur lesquelles vous empilez des outils de commodité.

La catégorie des plateformes gérées existe et est bien financée, mais pour un développeur qui vit déjà dans SSH et Git, une machine auto-hébergée offre plus de contrôle à moindre coût. Ce guide couvre la voie DIY.

Les Deux Patterns : tmux vs. systemd

Il existe deux objectifs distincts que les lecteurs confondent régulièrement, et ils nécessitent des configurations différentes. Exécuter un agent de codage CLI comme Claude Code dans une session à laquelle on s’attache et se détache constitue le pattern tmux. Héberger un agent en tant que service HTTP toujours disponible et accessible via API constitue le pattern systemd. Choisir le mauvais est l’erreur structurelle la plus courante dans les configurations d’agents distants.

Utilisez tmux lorsque vous souhaitez observer et piloter l’agent — saisir des instructions, approuver des actions, lire la sortie. Utilisez systemd lorsque l’agent est un service qui accepte des requêtes et s’exécute sans humain connecté. La plupart des personnes exécutant Claude Code de manière interactive veulent tmux. La plupart des personnes exposant un agent derrière une API veulent systemd. Certaines configurations utilisent les deux.

Exécuter Claude Code à Distance : La Pile Gratuite Canonique

La pile gratuite canonique pour exécuter Claude Code à distance comprend une machine Linux, Tailscale pour la couche réseau privée, OpenSSH plus mosh pour la connexion, et tmux pour les sessions persistantes. Cette section constitue la séquence de configuration prête à copier-coller. Effectuez le durcissement de sécurité de la section suivante avant de considérer la machine comme prête pour la production.

Installer Tailscale

Tailscale construit un mesh chiffré WireGuard entre vos appareils : une fois installé, votre machine distante obtient une adresse 100.x.x.x stable accessible depuis n’importe quel appareil authentifié sans ouvrir de ports de pare-feu, configurer de DNS dynamique, ni toucher à votre routeur. Le protocole sous-jacent de Tailscale est WireGuard, et le plan Personnel gratuit couvre jusqu’à 6 utilisateurs avec un nombre illimité d’appareils personnels selon la refonte tarifaire d’avril 2026 — vérifiez les limites actuelles avant de vous y fier.

Installez-le sur la machine distante conformément à la documentation d’installation officielle :

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

La commande tailscale up affiche une URL d’authentification. Ouvrez-la, connectez-vous, et la machine rejoint votre tailnet. Exécutez tailscale ip -4 pour obtenir son adresse 100.x.x.x. Installez Tailscale sur votre ordinateur portable et votre téléphone de la même manière, authentifiez-les sur le même compte, et les trois appareils peuvent désormais se joindre directement.

Une mise en garde qui fait échouer les configurations silencieusement — que nous avons rencontrée nous-mêmes : n’activez pas le serveur SSH intégré de Tailscale avec tailscale up --ssh si vous prévoyez d’utiliser mosh. Tailscale SSH exécute le propre serveur SSH de Tailscale, pas OpenSSH, et mosh doit exécuter mosh-server via un vrai OpenSSH et analyser sa sortie pour initialiser une session — ce que Tailscale SSH ne prend pas en charge. Gardez OpenSSH installé et en cours d’exécution aux côtés de Tailscale pour que mosh puisse se connecter.

Configurer SSH et mosh

SSH vous donne le shell ; mosh le maintient utilisable sur des connexions mobiles instables en survivant aux changements d’adresse IP et aux itinérances. mosh nécessite qu’un port UDP dans la plage 60000–61000 soit accessible, selon la documentation mosh. Sur un mesh Tailscale, cette plage est déjà accessible entre les appareils authentifiés, donc aucune configuration de routeur n’est nécessaire.

Installez mosh sur le serveur et votre client :

sudo apt update && sudo apt install -y mosh tmux

Connectez-vous depuis votre ordinateur portable en utilisant l’adresse Tailscale :

mosh youruser@100.x.x.x

Si mosh échoue à se connecter, revenez au simple ssh youruser@100.x.x.x pour confirmer que la machine est accessible, puis vérifiez qu’OpenSSH (et non Tailscale SSH) répond.

Créer des Sessions tmux Persistantes

tmux est ce qui maintient l’agent actif après votre déconnexion. Démarrez une session, exécutez Claude Code à l’intérieur, détachez-vous, et l’agent continue de fonctionner ; rattachez-vous plus tard depuis n’importe quel appareil pour le vérifier ou le piloter.

Nommez les sessions tmux d’après le projet, pas l’outil. Utilisez tmux new-session -s monprojet plutôt que tmux new-session -s claude — lorsque vous exécutez trois agents sur trois dépôts, tmux ls doit vous indiquer quelle session est laquelle :

tmux new-session -s myproject
# à l'intérieur de la session :
cd ~/code/myproject
claude
# se détacher avec Ctrl-b puis d

Le flag -s nomme la session. Rattachez-vous depuis n’importe où avec tmux attach -t myproject, ou listez tout ce qui s’exécute avec tmux ls. Ce cycle de détachement et de rattachement est toute la boucle interactive d’agent distant : fermez votre ordinateur portable, rattachez-vous depuis votre téléphone via mosh, lisez ce que l’agent a fait, donnez-lui la prochaine instruction.

La Ligne de Base de Sécurité

Une machine distante exécutant un agent de codage est une cible d’attaque de grande valeur : elle détient un accès au shell, des clés API et souvent des identifiants de dépôt. Lier le port de l’agent à 0.0.0.0 sur un VPS public, même brièvement pour un test de fumée, met les trois en danger. Durcissez la machine avant de lui faire confiance avec quoi que ce soit. Cette section n’est pas optionnelle.

Clés SSH Uniquement

Désactivez l’authentification par mot de passe afin que le seul moyen d’accès soit une clé que vous détenez. Éditez /etc/ssh/sshd_config et définissez :

PasswordAuthentication no
PermitRootLogin no

La directive PasswordAuthentication no désactive la connexion par mot de passe, et PermitRootLogin no bloque le SSH root direct — toutes deux documentées dans le manuel sshd_config. Une erreur courante est d’éditer le mauvais fichier ; ces directives appartiennent à /etc/ssh/sshd_config, pas à une configuration client. Appliquez avec sudo systemctl restart ssh. Confirmez que votre clé fonctionne dans une session séparée avant de fermer celle que vous avez, pour qu’une faute de frappe ne vous bloque pas.

Garder le Mesh Privé

Le mesh de Tailscale est déjà authentifié, mais vous pouvez restreindre quels appareils atteignent quels ports en utilisant les ACL Tailscale. Une politique ACL restreint le trafic entre les appareils étiquetés — par exemple, en autorisant uniquement votre ordinateur portable et votre téléphone à atteindre la machine agent, et rien d’autre sur le tailnet. Pour une configuration mono-utilisateur, le « tout autoriser au sein de votre tailnet » par défaut est raisonnable ; ajoutez des ACL lorsque d’autres personnes ou des appareils non fiables partagent le réseau.

Ne Jamais Lier l’Agent à 0.0.0.0

Lors du test de fumée d’un service lié localement, utilisez curl http://127.0.0.1:9000/health depuis le serveur lui-même plutôt que de lier temporairement à 0.0.0.0. Sur un VPS sans règle de pare-feu bloquant le port 9000, ce changement d’une ligne expose votre agent à l’internet public pendant toute la durée d’exécution du processus. Liez à 127.0.0.1 et accédez au service via Tailscale ou un proxy inverse — jamais directement.

Garder les Secrets Hors du Fichier d’Unité

Ne jamais mettre de clés API dans la ligne Environment= d’un fichier d’unité systemd — elles apparaissent dans la sortie de systemctl show. Utilisez EnvironmentFile=/etc/myagent/secrets.env pour garder les valeurs hors du fichier d’unité et de systemctl show, conformément à la documentation systemd.exec. Verrouillez le fichier :

sudo mkdir -p /etc/myagent
sudo chmod 640 /etc/myagent/secrets.env
sudo chown root:myagent /etc/myagent/secrets.env

Soyez précis sur ce que cela vous apporte : EnvironmentFile= garde les secrets hors du fichier d’unité et de systemctl show, mais une fois chargées, les valeurs restent lisibles dans l’environnement du processus en cours d’exécution et via D-Bus. Pour une véritable protection des secrets, utilisez LoadCredential= de systemd, documenté dans le guide des credentials systemd, qui transmet les credentials via un répertoire restreint plutôt que l’environnement du processus.

Maintenir un Agent de Service Actif : L’Unité systemd

Pour un agent qui s’exécute en tant que service HTTP toujours disponible plutôt qu’une session interactive, utilisez une unité systemd liée à 127.0.0.1 avec Restart=always. C’est le pattern systemd : le service démarre au démarrage, redémarre après un crash, journalise dans le journal, et ne touche jamais directement à un port public. EnvironmentFile= est une directive systemd fondamentale de longue date, disponible sur chaque version systemd actuelle, conformément à la documentation systemd.exec.

Créez /etc/systemd/system/my-agent.service :

[Unit]
Description=My Agent Service
After=network.target

[Service]
User=myagent
Group=myagent
WorkingDirectory=/home/myagent/app
EnvironmentFile=/etc/myagent/secrets.env
ExecStart=/home/myagent/app/venv/bin/uvicorn main:app --host 127.0.0.1 --port 9000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Chaque directive justifie sa présence. After=network.target attend que le réseau soit disponible. L’exécution avec un User/Group dédié limite le rayon d’explosion si l’agent est compromis. EnvironmentFile= charge les secrets depuis le fichier verrouillé. ExecStart exécute le serveur directement depuis le virtualenv du projet — sans scripts d’encapsulation — lié à 127.0.0.1 pour que le port ne soit jamais accessible publiquement. Restart=always avec RestartSec=5 relance le service cinq secondes après tout crash.

Activez et démarrez-le :

sudo systemctl daemon-reload
sudo systemctl enable --now my-agent
sudo systemctl status my-agent

Pour exposer le service en toute sécurité, placez un proxy inverse devant le port lié à localhost. Un proxy_pass nginx vers 127.0.0.1 maintient l’upstream inaccessible directement depuis l’extérieur tout en terminant TLS à la périphérie :

server {
    listen 443 ssl;
    server_name agent.example.com;

    ssl_certificate     /etc/letsencrypt/live/agent.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/agent.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Provisionnez le certificat avec Certbot, qui automatise l’émission et le renouvellement Let’s Encrypt. Pour une configuration mono-utilisateur, vous n’avez souvent pas besoin d’un nom d’hôte public du tout — accéder au service via Tailscale à 100.x.x.x:9000 depuis des appareils authentifiés évite entièrement la surface publique.

Accéder à la Machine depuis Mobile

Vous accédez à un agent distant depuis un téléphone de la même manière que depuis un ordinateur portable — via Tailscale, avec un client terminal ou un terminal navigateur devant. Le paysage des outils évolue rapidement à mi-2026 ; considérez ces options comme des améliorations facultatives, pas comme une infrastructure fondamentale.

Les options durables sont un client SSH mobile (plusieurs prennent en charge les connexions persistantes et l’authentification par clé) plus tmux, ou mosh pour les connexions qui survivent aux changements de réseau. Par-dessus cela se trouvent des outils de terminal navigateur. ttyd expose un terminal via le web. vibetunnel (sous licence MIT, Mac en premier avec une version npm Linux multiplateforme) proxifie un terminal dans le navigateur et a été conçu pour surveiller les agents Claude Code, avec accès distant via Tailscale. Si vous exécutez un terminal navigateur, gardez-le lié à localhost et accédez-y via Tailscale — exposer un terminal web publiquement est la même erreur 0.0.0.0 sous une forme différente.

Le Remote Control natif de Claude Code couvre le cas léger : HTTPS sortant uniquement, pilotage depuis un téléphone, sans ports entrants. C’est le moyen le plus rapide de guider une session active unique. La pile DIY reste ce vers quoi vous vous tournez lorsque le travail survit à n’importe quel terminal.

Le Flux de Travail Quotidien

La boucle de redéploiement quotidien sur une machine distante tient en trois commandes : récupérer le code, redémarrer le service, suivre les journaux. Pour un agent géré par systemd, c’est :

cd ~/app && git pull origin main
source venv/bin/activate && pip install -r requirements.txt
sudo systemctl restart my-agent
journalctl -u my-agent -f

git pull récupère le dernier code, l’installation des dépendances prend en compte les nouvelles exigences, systemctl restart redémarre le service, et journalctl -u my-agent -f suit les journaux du service en temps réel pour confirmer un démarrage propre — journalctl lit le journal systemd, documenté sur freedesktop.org. Pour un agent tmux interactif, la boucle est encore plus simple : rattachez-vous avec tmux attach -t myproject, faites git pull, et laissez l’agent continuer.

Conclusion

Appuyez-vous sur les primitives qui survivent aux outils d’encapsulation : SSH et Tailscale pour le réseau, tmux pour les sessions que vous pilotez, systemd pour les services qui s’exécutent sans surveillance, et une ligne de base de sécurité qui maintient le port de l’agent hors de l’internet public. Choisissez délibérément le pattern tmux ou le pattern systemd selon que vous pilotez un agent ou en hébergez un, durcissez la machine avant de lui confier des clés API, puis ajoutez le Remote Control natif ou un terminal navigateur comme commodité. Commencez avec une machine Linux fraîche et la commande d’installation Tailscale ci-dessus — le reste est composable à partir de là.

FAQ

Pourquoi mon agent s'arrête-t-il quand je me déconnecte de SSH ?

Une session SSH ordinaire lie le processus de l'agent à votre terminal, donc fermer la connexion envoie un signal de raccrochage qui le tue. Exécutez plutôt l'agent dans une session tmux : démarrez-la avec tmux new-session -s monprojet, lancez l'agent, puis détachez-vous avec Ctrl-b suivi de d. Le processus continue de s'exécuter sur le serveur, et vous vous rattachez plus tard depuis n'importe quel appareil avec tmux attach -t monprojet.

Quand devrais-je utiliser le Remote Control natif de Claude Code plutôt qu'une configuration DIY avec tmux et SSH ?

Utilisez le Remote Control natif lorsque vous avez seulement besoin de piloter une session active unique depuis votre téléphone ou navigateur sans infrastructure, car il utilise le HTTPS sortant uniquement et n'ouvre aucun port entrant. Il est mono-session et s'arrête avec le terminal qui l'a lancé, donc pour un travail toujours actif, sans interface ou multi-projets devant survivre aux déconnexions, construisez la pile DIY sur SSH, Tailscale, tmux et systemd.

mosh fonctionne-t-il sur un réseau Tailscale ?

Oui, mosh fonctionne sur un mesh Tailscale car la plage de ports UDP 60000 à 61000 qu'il nécessite est déjà accessible entre les appareils authentifiés, donc aucune configuration de routeur n'est nécessaire. Le seul cas d'échec est l'activation du propre serveur SSH de Tailscale avec tailscale up --ssh, qui remplace OpenSSH ; mosh doit exécuter mosh-server via un vrai OpenSSH pour s'initialiser, donc gardez OpenSSH installé et en cours d'exécution aux côtés de Tailscale.

Quelle est la différence entre EnvironmentFile et LoadCredential pour les secrets dans systemd ?

EnvironmentFile charge les valeurs depuis un fichier externe afin qu'elles restent hors du fichier d'unité et de la sortie de systemctl show, mais les valeurs restent lisibles dans l'environnement du processus en cours d'exécution et via D-Bus. LoadCredential est plus robuste car il transmet les secrets via un répertoire restreint plutôt que l'environnement du processus, les maintenant hors de portée de l'environnement du processus en cours d'exécution. Utilisez EnvironmentFile pour la configuration et LoadCredential pour les véritables secrets.