Déploiement de Claude Code sur un Mac distant : SSH 2026

La documentation de Claude Code distingue trois décisions de permission — autoriser, demander confirmation ou refuser — et Apple prévoit un accès distant limité à certains comptes via Remote Login. Ce point suffit à fixer la méthode : si le projet utilise Xcode, Simulator, Keychain ou une autre capacité propre à macOS, le déploiement de Claude Code sur un Mac distant est le choix adapté. Pour un projet purement multiplateforme, il est inutile de payer un environnement macOS supplémentaire. Dans tous les cas, il faut préparer un compte isolé, une connexion SSH par clé, des règles de projet, une frontière de secrets et une session récupérable avant de laisser l’agent modifier le code. (documentation officielle des permissions Claude Code)

Cet article s’adresse aux développeurs Windows ou Linux qui doivent faire fonctionner Claude Code avec un outil macOS, aux développeurs mobiles qui veulent isoler les tâches d’IA de leur Mac principal et aux ingénieurs plateforme qui doivent livrer un nœud distant réutilisable, contrôlable et supprimable.

Dernière mise à jour : 17 août 2026. Les étapes ont été vérifiées à partir de la documentation officielle Claude Code et des instructions Apple relatives à Remote Login ; les noms d’options et les commandes doivent être revérifiés avant publication si ces documentations évoluent.

Le bon choix dépend d’abord des dépendances macOS

Un Mac distant n’est pas automatiquement une meilleure machine de développement. Il devient pertinent lorsque le dépôt contient des dépendances que Linux ou Windows ne reproduisent pas proprement.

La décision peut être prise à partir d’une liste de dépendances, et non d’une préférence personnelle :

• projet iOS ou macOS nécessitant Xcode, xcodebuild ou Simulator ;
• signature d’application utilisant les certificats et trousseaux macOS ;
• tests qui doivent vérifier un comportement de l’interface ou du système Apple ;
• traitement audio ou vidéo dépendant d’outils macOS, de codecs installés localement ou d’un flux de production Final Cut Pro ;
• automatisation de design, de rendu ou de génération de médias qui doit être exécutée sur une machine Apple ;
• nœud CI/CD qui doit rester disponible sans monopoliser le poste de travail principal.

À l’inverse, un service web en Python, Go, Node.js ou Rust qui ne dépend ni de Xcode ni d’un outil macOS peut rester sur l’environnement existant. Ajouter un Mac dans ce cas augmente la surface d’administration : nouvel utilisateur, nouvelles clés SSH, nouveau stockage de secrets et nouvelle facture.

Dépendance du projet	Mac distant recommandé ?	Vérification à effectuer
Xcode ou xcodebuild	Oui	Compilation et test sur le nœud macOS
Simulator	Oui	Lancement d’un appareil simulé et exécution d’un test
Keychain ou signature Apple	Oui, avec contrôle renforcé	Accès au trousseau, certificats et profils
Service web multiplateforme	Généralement non	Pipeline reproductible sur l’environnement actuel
Audio, vidéo ou design macOS	Selon les outils utilisés	Test du logiciel, des codecs et des volumes
Agent de développement sans dépendance Apple	Pas nécessairement	Comparaison du coût et de la maintenance

Le choix doit également tenir compte de la persistance. Une machine ponctuelle convient à un essai. Un nœud qui exécute régulièrement des tests, des rendus ou des tâches planifiées doit conserver un répertoire de travail, une méthode de reconnexion et une politique de récupération après redémarrage.

Sans Mac local, est-il possible d’exécuter Claude Code à distance ? Oui. Le poste local n’a besoin que d’un client SSH et d’un navigateur pour l’authentification interactive. Claude Code et les outils macOS sont installés sur le Mac distant ; le code, les dépendances et les journaux restent sur ce nœud. Cette séparation est particulièrement utile lorsque le poste principal est sous Windows ou Linux, mais elle ne dispense pas de sécuriser le compte distant et les secrets du projet. (guide officiel d’installation de Claude Code)

Avant Claude Code : construire une chaîne SSH vérifiable

La première erreur consiste à installer l’agent avant de prouver que la connexion distante est fiable. Apple indique que Remote Login permet l’accès par SSH ou SFTP et que la liste « Only these users » sert à limiter les comptes autorisés. Il faut donc commencer par le compte, le réseau et l’identité cryptographique, puis seulement installer les outils. (instructions Apple pour Remote Login)

1. Créer un compte de travail distinct

Le compte utilisé par Claude Code ne doit pas être le compte administrateur quotidien. Il doit disposer :

• d’un répertoire de travail dédié ;
• d’un accès Git correspondant au projet ;
• de permissions suffisantes pour les outils de compilation ;
• d’un accès explicitement documenté aux certificats ou trousseaux nécessaires ;
• d’aucun accès implicite aux répertoires personnels d’autres utilisateurs.

Sur le Mac, activez Remote Login dans Réglages Système > Général > Partage, puis limitez l’accès à l’utilisateur de travail. N’activez pas l’accès complet au disque distant par défaut. Apple précise que cette option élargit fortement ce que les utilisateurs distants peuvent atteindre.

2. Préparer une clé SSH et vérifier l’empreinte

Depuis le poste local, créez ou sélectionnez une clé dédiée au nœud de développement. L’exemple ci-dessous utilise un hôte fictif et un compte fictif :

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_claude_mac
ssh-copy-id -i ~/.ssh/id_ed25519_claude_mac devagent@mac-lab.example

Si ssh-copy-id n’est pas disponible, ajoutez la clé publique au fichier ~/.ssh/authorized_keys du compte distant par un autre canal sécurisé. Ne transmettez jamais la clé privée dans un dépôt, une capture d’écran ou un ticket.

Lors de la première connexion, vérifiez l’empreinte affichée avec celle fournie par l’administrateur du Mac ou par la console de livraison. Une connexion réussie ne prouve pas que vous êtes sur le bon hôte.

3. Créer un alias SSH explicite

Le fichier local ~/.ssh/config peut contenir un alias qui évite les erreurs de compte ou de port :

Host mac-claude-lab
    HostName mac-lab.example
    User devagent
    IdentityFile ~/.ssh/id_ed25519_claude_mac
    IdentitiesOnly yes
    ServerAliveInterval 30
    ServerAliveCountMax 3

Les valeurs ServerAliveInterval et ServerAliveCountMax ne remplacent pas une session persistante. Elles servent uniquement à détecter plus proprement une liaison interrompue. Le nom d’hôte et le compte de cet exemple sont fictifs.

4. Tester autre chose qu’une connexion interactive

La chaîne SSH doit passer plusieurs contrôles :

ssh mac-claude-lab 'id -un && pwd && echo "$SHELL"'
printf 'test distant\n' > /tmp/ssh-check.txt
scp /tmp/ssh-check.txt mac-claude-lab:~/ssh-check.txt
ssh mac-claude-lab 'cat ~/ssh-check.txt && rm ~/ssh-check.txt'
ssh mac-claude-lab 'command -v git; command -v bash; command -v zsh'

Répétez ensuite le test après fermeture du terminal local. Contrôlez également que l’environnement non interactif trouve bien les commandes importantes. Les différences entre un shell interactif et un shell lancé par SSH expliquent souvent les erreurs « commande introuvable » dans les scripts.

Contrôle	Résultat attendu	Échec typique
Identité du compte	Utilisateur de travail, pas administrateur par défaut	Clé installée sur le mauvais compte
Répertoire courant	Chemin de projet prévu	Dépôt placé dans un volume temporaire
Transfert SFTP/SCP	Fichier lisible puis supprimable	Permission ou chemin incorrect
Recherche de commandes	Git, shell et outils visibles	Profil shell non chargé
Reconnexion	Nouvelle session fonctionnelle	Règle réseau ou agent SSH expiré
Empreinte hôte	Empreinte connue	Risque d’interception ou d’erreur d’adresse

Attention : un accès SSH par mot de passe peut fonctionner tout en restant inadapté à une automatisation. Pour un nœud durable, la clé doit être révocable individuellement et associée à un compte identifiable.

Installer Claude Code et séparer les modes d’authentification

Une fois SSH validé, connectez-vous au Mac distant et installez Claude Code depuis la méthode officielle. La documentation actuelle propose l’installation native ou Homebrew sur macOS. Après l’installation, les deux premières commandes de contrôle sont :

claude --version
claude doctor

La première confirme que l’exécutable est trouvé. La seconde fournit un diagnostic plus large de l’installation et de la configuration. La documentation recommande également de démarrer Claude Code depuis le répertoire du projet plutôt que depuis un dossier générique.

Authentification interactive par navigateur

Depuis une session SSH, la commande claude peut demander une authentification dans un navigateur. Le navigateur ouvert sur le poste local ne doit pas être confondu avec celui du Mac distant. Le flux consiste à déclencher la connexion sur le Mac, ouvrir l’URL fournie sur le poste local, terminer l’autorisation puis revenir au terminal distant.

Après une connexion SSH, comment terminer l’authentification ? Il faut lancer Claude Code dans la session distante, suivre l’URL ou le code affiché, puis effectuer l’autorisation dans le navigateur local. Si le retour automatique vers le terminal ne fonctionne pas, le résultat doit être confirmé avec l’état de session ou la commande de diagnostic, et non supposé à partir de la page web.

Sur macOS, les identifiants gérés par Claude Code sont stockés dans le trousseau chiffré du système. Cette protection est liée au compte macOS qui exécute Claude Code. Elle ne signifie pas que tous les certificats de signature du projet sont automatiquement disponibles, ni qu’un second utilisateur du même Mac pourra reprendre la session. (documentation officielle de l’authentification Claude Code)

Authentification non interactive pour scripts et CI

L’usage personnel interactif et l’automatisation ne doivent pas partager le même mécanisme :

• session interactive : connexion par navigateur, compte individuel et approbation des actions ;
• script ou CI : jeton ou clé fourni par le gestionnaire de secrets du pipeline, sans l’inscrire dans le dépôt ;
• équipe : compte et politique séparés, avec rotation et révocation documentées.

La documentation officielle indique que claude setup-token peut produire un jeton OAuth destiné aux pipelines et environnements sans navigateur. Le jeton est affiché dans le terminal et doit être injecté dans la variable d’environnement prévue par le script ; il ne doit pas être copié dans l’historique, une capture ou un fichier versionné.

Avant d’aller plus loin, vérifiez :

claude doctor
env | grep -E 'ANTHROPIC|CLAUDE'

Si une variable d’API ancienne entre en conflit avec une session par abonnement, elle doit être retirée ou gérée explicitement. Les secrets affichés dans la sortie doivent être masqués avant tout partage de diagnostic.

Initialiser le dépôt et les outils macOS

Le code doit être placé dans un répertoire contrôlé, par exemple ~/workspaces/mobile-demo, et non directement dans le dossier personnel sans séparation. Récupérez le dépôt, vérifiez l’identité Git, puis contrôlez l’existence des outils nécessaires :

mkdir -p ~/workspaces
cd ~/workspaces
git clone git@example.invalid:team/mobile-demo.git
cd mobile-demo

git config user.name
git config user.email
command -v xcodebuild
xcodebuild -version

L’adresse du dépôt est volontairement fictive. Les clés Git doivent être installées séparément et avec la même prudence que les clés SSH d’accès au Mac.

Pour un projet iOS, ajoutez une vérification adaptée au dépôt. Par exemple, le script de compilation peut être appelé manuellement avant de l’être par Claude Code. Pour un projet audio, vidéo ou design, remplacez cette étape par l’ouverture d’un petit fichier de test, l’inspection d’un codec ou le rendu d’un artefact court. Le but est de vérifier l’outil réel, pas seulement la présence d’un binaire.

Documenter le projet dans CLAUDE.md

Claude Code charge les fichiers CLAUDE.md selon leur portée. Un fichier placé à la racine du projet peut décrire les commandes de test, l’architecture, les conventions et les répertoires autorisés. Les paramètres partagés peuvent être placés dans .claude/settings.json, tandis que les réglages personnels non versionnés doivent rester dans .claude/settings.local.json. (documentation officielle des réglages Claude Code)

Un fichier minimal peut contenir :

# Règles du projet

- Modifier uniquement `Sources/`, `Tests/` et `Scripts/`.
- Ne jamais lire `.env`, `Certificates/` ou `Private/`.
- Lancer `./Scripts/test-ci.sh` après toute modification.
- Ne pas modifier les fichiers de signature.
- Préparer un plan avant les changements qui touchent l’architecture.
- Ne jamais pousser directement sur la branche principale.

Le fichier guide l’agent, mais il ne constitue pas une barrière de sécurité. Les refus de lecture, les limites de commande et le bac à sable doivent être configurés séparément. La documentation Claude Code distingue précisément le contexte fourni par CLAUDE.md des contrôles qui imposent une limite même lorsque l’agent prend une mauvaise décision.

Validez ensuite avec une tâche réduite :

1. demander une lecture de l’architecture ;
2. faire modifier un fichier non sensible ;
3. lancer un test rapide ;
4. examiner le diff ;
5. revenir en arrière si le résultat n’est pas conforme.

Cette tâche doit être réelle mais réversible. Un changement de libellé, un test unitaire isolé ou une correction de documentation convient mieux qu’une migration de base de données.

Appliquer les permissions, le bac à sable et les limites réseau

Les permissions de Claude Code suivent trois actions principales : allow, ask et deny. Les règles sont évaluées dans l’ordre refus, demande, autorisation ; une règle de refus doit donc protéger les chemins sensibles avant toute règle plus large. (règles officielles de permissions Claude Code)

Un exemple de .claude/settings.json :

{
  "permissions": {
    "allow": [
      "Read(./Sources/**)",
      "Read(./Tests/**)",
      "Edit(./Sources/**)",
      "Edit(./Tests/**)",
      "Bash(./Scripts/test-ci.sh)"
    ],
    "ask": [
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(xcodebuild *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./Certificates/**)",
      "Read(./Private/**)",
      "Read(./config/credentials.json)"
    ]
  }
}

Les motifs doivent être adaptés à la structure réelle du dépôt. Une règle trop large sur Bash peut laisser passer des commandes réseau ou des opérations de suppression inattendues. Claude Code précise que les permissions et le bac à sable sont complémentaires : les premières déterminent ce que l’agent peut demander, tandis que le bac à sable impose une restriction au niveau du système pour les commandes Bash et leurs processus enfants.

Activer le bac à sable comme seconde barrière

La commande /sandbox permet d’activer le mode de bac à sable. La configuration doit ensuite être testée dans trois cas :

• lecture et installation d’une dépendance autorisée ;
• tentative de lecture d’un fichier de secret ;
• commande visant un chemin ou un domaine non autorisé.

Si le bac à sable est obligatoire pour le modèle de menace retenu, configurez sandbox.failIfUnavailable à true. Le comportement par défaut peut afficher un avertissement puis exécuter la commande sans bac à sable lorsque celui-ci ne peut pas démarrer ; ce comportement est inadapté à une politique qui exige un échec fermé. (documentation officielle du bac à sable)

Expérience de terrain : une règle qui refuse WebFetch ne bloque pas nécessairement un curl lancé par Bash. Pour limiter réellement le réseau, il faut combiner les permissions avec les domaines autorisés du bac à sable. (documentation officielle de l’administration Claude Code)

Contrôlez les règles actives avec /permissions, les sources de configuration avec /status et les problèmes d’installation avec /doctor. Ces commandes évitent de croire qu’un fichier JSON est chargé alors qu’il se trouve dans le mauvais répertoire ou contient une erreur de schéma.

Maintenir la session après une coupure SSH

Une session Claude Code directement attachée au terminal SSH peut devenir inutilisable lorsque le réseau local tombe ou que le terminal est fermé. Pour un travail de plusieurs minutes ou davantage, démarrez une session tmux sur le Mac distant :

ssh mac-claude-lab
tmux new -s claude-work
cd ~/workspaces/mobile-demo
claude

Après une coupure :

ssh mac-claude-lab
tmux attach -t claude-work

Claude Code signale deux particularités lorsque l’outil fonctionne dans tmux : le raccourci Shift+Enter et les notifications peuvent ne pas être transmis correctement au terminal extérieur. La documentation recommande d’ajouter les paramètres suivants à ~/.tmux.conf, puis de recharger la configuration. (configuration officielle du terminal Claude Code)

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

Que se passe-t-il si SSH se déconnecte pendant une tâche ? La récupération dépend de la présence d’une session persistante. Si Claude Code tourne dans tmux, reconnectez-vous au même compte et rattachez-vous à la session. Si le processus a été tué, examinez le dépôt, le diff et les journaux avant de relancer une tâche. Ne demandez pas immédiatement une seconde modification : commencez par déterminer si la première a été appliquée partiellement.

La réception du nœud avant mise en production

Le dernier contrôle doit utiliser le vrai flux de travail, avec une tâche courte et réversible. Il doit confirmer simultanément l’accès macOS, la sécurité et la récupération.

Avant de mettre le Mac distant en service, que faut-il contrôler ?

• le compte SSH est indépendant et la clé peut être révoquée ;
• l’empreinte de l’hôte est documentée ;
• le dépôt est récupérable depuis une source sauvegardée ;
• claude --version et claude doctor ne signalent pas d’erreur ;
• l’authentification interactive et l’authentification d’automatisation sont séparées ;
• Xcode, Simulator, Keychain ou les outils audio/vidéo nécessaires sont réellement accessibles ;
• CLAUDE.md décrit les commandes de test et les répertoires autorisés ;
• les fichiers .env, certificats, profils et configurations de production sont refusés ;
• le bac à sable bloque une lecture et une commande réseau hors périmètre ;
• une session tmux survit à la fermeture du terminal ;
• un redémarrage du Mac laisse une procédure claire de reprise ;
• le dépôt peut être remis à l’état initial par Git.

Pour les équipes, ajoutez un registre de cycle de vie : date de création du compte, propriétaire de la clé, emplacement des sauvegardes, méthode de rotation des secrets, version de Claude Code retenue et responsable de la mise à jour. La documentation de configuration prévoit des portées utilisateur, projet, locale et gérée ; cette distinction permet de séparer les préférences personnelles des règles qui doivent rester imposées à tous les utilisateurs.

Un nœud destiné à un projet de design ou de vidéo doit aussi être validé avec un fichier représentatif, et non avec un simple test de compilation. Pour un pipeline audio, mesurez la lecture et l’export d’un court échantillon. Pour Xcode, vérifiez la compilation, les tests et l’accès aux éléments de signature avec un compte dont les droits sont connus.

Quand le Mac distant devient préférable au poste actuel

Un poste Windows ou Linux reste souvent plus simple pour un service web multiplateforme. Mais il atteint rapidement ses limites lorsque Xcode, Simulator, Keychain ou des applications macOS de création entrent dans la chaîne. Les solutions virtualisées ou les bricolages locaux ajoutent alors des couches de compatibilité, des problèmes de périphériques et une maintenance difficile à reproduire.

La location d’un Mac auprès de ProxyMac devient pertinente lorsque le besoin est temporaire, lorsque l’équipe doit tester un environnement Apple sans acheter de matériel ou lorsque le nœud doit rester accessible en continu. L’intérêt n’est pas de remplacer tous les postes de travail : il consiste à fournir un environnement macOS isolé, avec SSH, VNC ou console web, pour la durée réelle du projet. Avant de choisir, consultez les informations de connexion à la console ProxyMac et les règles de confidentialité du service.

Le poste actuel conserve toutefois un avantage pour les charges longues et prévisibles, pour les équipes qui possèdent déjà un Mac correctement administré ou pour les workflows qui exigent un accès physique à des périphériques. La location n’est donc pas automatiquement la meilleure option : elle l’est surtout lorsque le coût d’achat, le délai de livraison ou la nécessité d’un nœud séparé pèsent davantage que la proximité du matériel local.

Pour une première mise en œuvre, la séquence la plus sûre reste la suivante : préparer un compte isolé, valider SSH, installer Claude Code, configurer les permissions, activer le bac à sable, lancer une petite tâche réversible, puis décider seulement après si le Mac doit devenir un nœud permanent. Ce processus limite les erreurs coûteuses et donne une preuve concrète que l’agent peut travailler sur macOS sans accéder aux secrets ni aux chemins de production.