VS Code Remote SSH vers un Mac distant : guide 2026

La règle de dépannage est simple : commencez par le SSH en ligne de commande, puis passez au journal Remote - SSH, à VS Code Server et enfin aux extensions. Si le terminal échoue aussi, restez sur les couches réseau, Remote Login et authentification ; s’il fonctionne mais que VS Code bloque, ne réinstallez pas immédiatement l’extension et ne supprimez pas le serveur distant sans conserver les preuves.

Cette méthode convient aux développeurs qui doivent accéder à un environnement macOS depuis Windows ou Linux, aux équipes DevOps qui maintiennent plusieurs nœuds de développement, ainsi qu’aux ingénieurs confrontés à une installation interrompue de VS Code Server ou à une reconnexion impossible après redémarrage.

Un cas revient souvent : la commande ssh ouvre bien une session sur le Mac distant, mais VS Code reste bloqué sur l’initialisation. Cette situation ne signifie pas que SSH est « cassé ». Le canal SSH peut être opérationnel alors que le téléchargement du serveur, son lancement, le tunnel ou l’extension distante échoue.

Remote - SSH installe et exécute VS Code Server sur l’hôte distant ; le client local n’est donc qu’une partie de la chaîne. La documentation officielle décrit cette architecture et confirme que les commandes ainsi que les extensions de développement s’exécutent sur la machine distante (fonctionnement officiel de Remote - SSH).

Journal à conserver avant toute modification

Avant de redémarrer, supprimer un dossier ou réinstaller une extension, nous vous recommandons de noter séparément les résultats suivants :

Cette séparation évite de confondre un délai d’authentification avec un problème de serveur. Elle est également indispensable si le nœud est partagé par plusieurs ingénieurs : un nettoyage trop rapide peut effacer l’indice qui permettait d’identifier un mauvais compte, un mauvais chemin ou un processus résiduel.

Les journaux se trouvent dans la palette de commandes avec Remote-SSH: Show Log. Pour les problèmes d’extensions déjà connectées, consultez aussi la sortie de l’hôte d’extensions distant, et non seulement celle de l’interface locale (procédure officielle de collecte des journaux).

La première décision dépend du résultat obtenu dans le terminal. Utilisez le même alias, le même fichier de configuration et, autant que possible, les mêmes options que VS Code :

ssh -v alias-du-mac

Ne remplacez pas immédiatement l’alias par une adresse différente. Un fichier ~/.ssh/config peut appliquer un User, un HostName, une IdentityFile, un port ou un agent différents selon le nom utilisé.

Sur le Mac, vérifiez Réglages Système > Général > Partage > Connexion à distance. Apple indique que cette option active l’accès par SSH ou SFTP et permet de choisir entre tous les utilisateurs et une liste limitée de comptes (guide Apple sur Connexion à distance).

Il faut contrôler deux éléments distincts : le service est-il activé, et le compte utilisé est-il autorisé ? Un utilisateur peut disposer d’un compte local valide tout en étant exclu de la liste des accès distants. Pour les opérations qui nécessitent une visibilité plus large du système de fichiers, vérifiez également le réglage d’accès complet au disque ; ne l’activez pas par défaut sur un poste partagé.

Dans un environnement public ou hébergé, ne supposez pas qu’un port ou une règle de pare-feu précis est disponible. Demandez plutôt quelle est l’adresse d’entrée, quelle politique filtre le trafic et si les connexions persistantes sont autorisées. La commande locale confirme uniquement ce qui est accessible depuis le poste de travail concerné.

Attention : ne publiez jamais une clé privée, un mot de passe, un jeton, une adresse complète ou une empreinte non anonymisée dans un ticket ou un article. Conservez les messages utiles, mais remplacez les identifiants et les hôtes avant partage.

Lorsque le terminal échoue avec une erreur de clé, d’utilisateur ou de permission, corrigez cette couche avant de revenir à VS Code. L’objectif est d’obtenir une connexion propre avec exactement le même hôte logique.

Commencez par afficher la configuration effectivement appliquée :

ssh -G alias-du-mac

Cette commande aide à repérer un User, un HostName ou un IdentityFile inattendu. Comparez ensuite avec le fichier ouvert par la commande VS Code Remote-SSH: Open Configuration File.... Les erreurs les plus coûteuses ne sont pas toujours cryptographiques : un alias peut simplement viser un autre Mac, un compte différent ou une ancienne clé.

Pour une clé protégée par phrase secrète, vérifiez que l’agent SSH est disponible dans le contexte depuis lequel VS Code est lancé. Sur Windows, Linux ou macOS, le terminal intégré et l’application graphique peuvent ne pas hériter exactement du même environnement. Si aucune invite n’apparaît, activez temporairement :

{
  "remote.SSH.showLoginTerminal": true,
  "remote.SSH.useLocalServer": false
}

Le réglage showLoginTerminal permet de voir une demande de mot de passe, de code complémentaire ou de phrase secrète qui resterait invisible dans l’interface. La documentation officielle recommande cette piste pour les authentifications alternatives et les agents SSH indisponibles (authentification et dépannage Remote - SSH).

Sur macOS, une clé privée trop permissive peut également être refusée par OpenSSH. Corrigez ses droits selon les règles de votre système, puis relancez la commande en mode verbeux. Ne copiez pas la sortie complète dans un rapport public : elle peut révéler des chemins, des noms d’utilisateur ou des hôtes internes.

Conditions de décision

• Si ssh alias-du-mac échoue avant l’ouverture de session, choisissez la branche réseau, Remote Login ou authentification ; ne touchez pas encore à VS Code Server.
• Si ssh alias-du-mac réussit mais que VS Code utilise un autre hôte, corrigez le fichier SSH ou remote.SSH.configFile, puis retestez avec le même alias.
• Si l’authentification demande une information que VS Code ne montre pas, activez remote.SSH.showLoginTerminal, sans enregistrer de secret dans les paramètres.
• Si le journal indique un tunnel refusé, vérifiez la transmission TCP côté serveur SSH et la politique de sécurité du nœud avant toute suppression.
• Si le même problème apparaît après un redémarrage, contrôlez l’adresse, le service Remote Login, l’autorisation du compte et les règles réseau avant de conclure à une corruption du serveur.

Une fois le terminal validé, concentrez-vous sur la phase d’installation et de lancement. Le serveur distant doit être téléchargé, transféré si nécessaire, décompressé dans le compte utilisateur puis démarré avec les droits attendus.

Les blocages les plus courants se répartissent en quatre catégories :

1. Téléchargement impossible : le Mac distant ne peut pas atteindre les services nécessaires, ou le poste local ne peut pas établir la sortie HTTPS attendue.
2. Décompression interrompue : espace insuffisant, archive incomplète ou outil système indisponible.
3. Droits incorrects : le compte SSH ne peut pas écrire dans son répertoire ou lancer les fichiers installés.
4. Processus résiduel : une ancienne session ou une installation partielle empêche le nouveau serveur de démarrer.

L’installation de VS Code Server nécessite une connectivité HTTPS sortante vers update.code.visualstudio.com et vscode.download.prss.microsoft.com. Les extensions peuvent également contacter marketplace.visualstudio.com et *.gallerycdn.vsassets.io (exigences réseau officielles). Un proxy local n’est pas automatiquement réutilisé sur le Mac distant : il faut donc vérifier les variables d’environnement ou la configuration de proxy du côté où le téléchargement s’effectue.

Le journal doit guider l’action. Un message de téléchargement ne se traite pas comme une erreur de permission, et une archive transférée avec succès ne prouve pas que le serveur peut démarrer. Vérifiez aussi les variables PATH, le répertoire personnel effectif et les droits sur les dossiers concernés.

La commande Remote-SSH: Kill VS Code Server on Host... peut résoudre une installation incohérente, mais elle arrête les processus concernés et supprime les fichiers du serveur distant. Nous la réservons donc à une situation où le journal montre clairement un état résiduel, après sauvegarde des informations utiles. La documentation officielle décrit cette opération et précise son effet (nettoyage officiel de VS Code Server).

Ne commencez pas par supprimer manuellement ~/.vscode-server. Cette action peut obliger VS Code à télécharger de nouveau les composants et efface des éléments utiles à l’analyse. Si le nettoyage est nécessaire, notez d’abord l’identifiant de version, le message d’erreur, le compte utilisé et le résultat obtenu après reconnexion.

Selon la documentation actuelle, un hôte macOS pris en charge doit disposer de macOS 10.14 ou version ultérieure avec Connexion à distance activée. La documentation indique également qu’un hôte distant nécessite au minimum 1 Go de mémoire, tandis que 2 Go et deux cœurs sont recommandés ; ces valeurs constituent des exigences documentaires, pas une garantie de performance pour un projet lourd (prérequis Remote - SSH). Pour des tâches audio, vidéo, design ou compilation simultanées, il faut donc examiner la charge réelle du Mac, l’espace disponible et les dépendances natives des extensions.

Une connexion affichée comme réussie ne signifie pas encore que l’environnement de développement est opérationnel. VS Code sépare les extensions locales de celles installées sur l’hôte SSH. Une extension d’interface peut rester locale alors qu’une extension de langage, de débogage ou de Git doit être installée sur le Mac distant (gestion officielle des extensions distantes).

Contrôlez l’emplacement de chaque extension dans le panneau Extensions. Une extension présente uniquement dans la catégorie locale ne pourra pas nécessairement analyser le code, lancer un outil ou accéder aux dépendances du projet sur le Mac.

Sur un Mac Apple Silicon, prêtez une attention particulière aux dépendances natives. Une extension peut se charger mais échouer lorsqu’elle invoque un binaire compilé pour une autre architecture. Vérifiez alors :

uname -m
which node
node --version
which python3
python3 --version
echo "$PATH"
git --version

Les résultats doivent être comparés avec ceux obtenus dans le terminal intégré de VS Code, et non avec un terminal local. Une différence de PATH explique souvent pourquoi une commande fonctionne en SSH interactif mais échoue dans une tâche, un débogueur ou une extension.

Les fichiers de configuration du shell constituent une autre source de divergence. Un shell interactif peut afficher des messages, charger un gestionnaire de versions ou modifier PATH, tandis qu’un shell non interactif utilisé par une tâche attend une sortie propre. Évitez donc les commandes d’affichage ou les scripts bruyants dans les fichiers de démarrage lorsque VS Code doit exécuter des commandes automatisées.

Enfin, validez le workspace au moyen d’une séquence complète :

• ouvrir le dépôt depuis la fenêtre distante ;
• créer un terminal réellement attaché au Mac ;
• exécuter la commande de test du projet ;
• lancer une opération Git ;
• démarrer le débogage ou la tâche principale ;
• fermer puis rouvrir la fenêtre distante.

Pour les projets audio, vidéo ou design, ajoutez le test de l’outil natif réellement utilisé, car l’ouverture de l’éditeur ne vérifie ni les codecs, ni les bibliothèques, ni les permissions de fichiers. Pour un pipeline de compilation, un indicateur vert ne suffit pas : le build doit être produit sur le Mac distant avec les variables et certificats attendus.

Pourquoi le terminal se connecte-t-il alors que VS Code Remote SSH échoue encore ?

SSH valide le réseau, le service et l’authentification, mais VS Code doit encore installer ou lancer VS Code Server, ouvrir un tunnel et charger les extensions distantes. Relevez le journal Remote - SSH, activez temporairement le terminal de connexion et comparez l’alias utilisé par VS Code avec celui de la commande ssh.

Que faire lorsque VS Code Server reste bloqué pendant son installation ?

Commencez par distinguer téléchargement, transfert, décompression, permission et démarrage. Contrôlez l’accès HTTPS sortant, l’espace disponible, le compte effectif et le répertoire personnel. Ne lancez Kill VS Code Server on Host qu’après avoir sauvegardé le journal et confirmé qu’une installation résiduelle est bien en cause.

Quels contrôles effectuer lorsque Remote SSH reste sur « Connexion à l’hôte » ?

Relancez la commande avec remote.SSH.showLoginTerminal activé afin de révéler une invite masquée. Si l’authentification réussit, recherchez ensuite un tunnel refusé, un proxy distant ou une détection incorrecte de la plateforme. Le bon test est une nouvelle connexion suivie de l’ouverture d’un dossier, pas seulement la disparition de la notification.

Comment récupérer la connexion après le redémarrage du Mac distant ?

Validez d’abord l’adresse et la commande SSH depuis un terminal. Sur le Mac, vérifiez Connexion à distance et la liste des comptes autorisés. Dans VS Code, lisez le journal avant de nettoyer le serveur. Si le problème revient à chaque redémarrage, examinez plutôt la disponibilité du nœud, le routage ou la persistance du service que l’installation locale de l’extension.

Après correction, nous vous conseillons de consigner une fiche d’acceptation réutilisable pour chaque Mac :

• [ ] Le nom d’hôte utilisé par VS Code correspond à celui validé en ligne de commande.
• [ ] Le compte est autorisé dans Connexion à distance.
• [ ] La clé et l’agent SSH fonctionnent sans exposer de secret.
• [ ] Le journal confirme le téléchargement ou le lancement correct de VS Code Server.
• [ ] Le terminal intégré affiche le bon PATH et les bons outils.
• [ ] Le dépôt s’ouvre avec les permissions attendues.
• [ ] Les extensions nécessaires sont installées côté distant.
• [ ] Une commande de build, de test ou de débogage s’exécute réellement.
• [ ] Une nouvelle connexion fonctionne après fermeture de la fenêtre.
• [ ] Le scénario a été vérifié après redémarrage du Mac, lorsque le nœud est destiné à rester disponible.

Pour approfondir la partie sécurité, vous pouvez consulter notre guide sur la connexion SSH à un Mac distant et la protection des clés. Si le problème vient d’un environnement mal préparé plutôt que de VS Code, la vérification d’un environnement de développement Mac distant fournit un autre angle de contrôle.

Si le Mac actuel reste indisponible, perd sa configuration après redémarrage, manque de droits administrateur ou ne permet pas de reproduire le problème de façon stable, il faut réévaluer le support lui-même. Un poste Windows ou Linux associé à une machine macOS instable oblige à maintenir deux environnements, à subir des interruptions difficiles à tracer et à répéter les installations sans garantie de retrouver le même état.

Dans ce cas, louer un Mac distant auprès de JEXCLOUD peut être plus cohérent pour un besoin temporaire de développement, de test ou de validation Apple Silicon : l’accès SSH complet permet de conserver la méthode de diagnostic présentée ici, tandis qu’un nœud distant disponible en continu évite de mobiliser immédiatement un achat matériel. En revanche, l’achat d’un Mac reste préférable pour une charge lourde permanente, un usage hors ligne ou un besoin d’interfaces physiques locales. Pour un projet borné dans le temps, vous pouvez examiner les solutions de Mac distant disponibles avec JEXCLOUD après avoir défini vos exigences de connexion et de persistance.

• Diagnostiquer un tunnel SSH vers un Mac distant : contrôles de santé et relance automatique
• Maintenir un service distant sur Mac avec launchd : démarrage, reconnexion et supervision