ssh-agent sous Windows : démarrer le service, ajouter vos clés, corriger les erreurs

29 sept. 2026 · Termalin Team sshssh-agentwindowstutorial

Vous avez mis une phrase secrète sur votre clé SSH, et maintenant Windows la réclame à chaque git push et à chaque ssh. La solution, c’est l’agent SSH : déverrouillez la clé une fois, et chaque connexion suivante signe sans rien demander. La subtilité, sous Windows, c’est qu’il n’existe pas un seul agent. Il y en a trois qui peuvent tourner en même temps, ils gardent les clés à des endroits distincts, et une clé chargée dans l’un est invisible pour les autres. Presque tous les problèmes d’agent du type « ça marchait hier » sous Windows sont en réalité un problème de mauvais agent. Ce guide commence donc par les nommer, puis met chacun en route, puis décode les erreurs que vous rencontrez vraiment.

Les trois agents, et pourquoi ils ne partagent pas les clés

Agent	Fourni avec	Où il écoute	Quel `ssh` le voit
OpenSSH Authentication Agent (un service Windows)	L’OpenSSH natif de Windows	canal nommé `\\.\pipe\openssh-ssh-agent`	`ssh.exe` dans `C:\Windows\System32\OpenSSH`
L’agent MSYS2 (`ssh-agent`)	Git for Windows / Git Bash	un socket de type Unix désigné par `SSH_AUTH_SOCK`	le `ssh` fourni avec Git Bash
Un agent Linux	dans votre distribution WSL	un socket Unix dans cette distribution	le `ssh` qui tourne dans WSL

La leçon de ce tableau : ssh-add dans Git Bash charge une clé dans l’agent MSYS2, et le ssh.exe natif de Windows ne la verra jamais — endpoint différent, magasin de clés différent. Choisissez un agent, chargez-y vos clés, et utilisez le ssh correspondant. Les mélanger est la cause profonde de la plupart des confusions ci-dessous. Le guide ssh-agent et ssh-add (en anglais) couvre les mécanismes multiplateformes ; cette page en est la moitié spécifique à Windows.

Le service OpenSSH Authentication Agent intégré

Les Windows 10 et 11 récents embarquent OpenSSH, et avec lui un service Windows qui fait tourner l’agent — mais il est désactivé par défaut. Activez-le une fois, depuis un PowerShell avec privilèges élevés (Exécuter en tant qu’administrateur) :

Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent

Automatic le démarre à chaque démarrage de la machine, c’est donc une configuration unique. Vérifiez le résultat :

Get-Service ssh-agent | Select-Object Status, StartType

Vous voulez Running et Automatic. À partir de là, dans un PowerShell ou un cmd normal (hors Git Bash), ssh-add dialogue avec ce service :

ssh-add                                 # load default keys (id_ed25519, id_rsa, …)
ssh-add $env:USERPROFILE\.ssh\id_ed25519  # load a specific key
ssh-add -l                              # list loaded key fingerprints

ssh-add -l est votre premier diagnostic pour tout échec de connexion — si la clé attendue n’apparaît pas, l’agent ne peut pas signer avec, quoi que le reste ait l’air correct.

Pour cesser de retaper ssh-add, laissez la première connexion charger la clé à votre place. Mettez ceci dans %USERPROFILE%\.ssh\config (le même fichier ssh_config (en anglais) qu’OpenSSH lit partout) :

Host *
    AddKeysToAgent yes

Désormais, le premier ssh qui a besoin d’une phrase secrète la demande une fois et charge la clé dans le service, en effet de bord. Et comme le git et le ssh natifs de Windows utilisent tous deux ce service, git push se met lui aussi à fonctionner en silence.

Erreur 1058 : « unable to start the ssh-agent service »

Vous lancez Start-Service ssh-agent et vous obtenez :

Start-Service : Service 'OpenSSH Authentication Agent (ssh-agent)' cannot be started due to the following error:
Cannot start service ssh-agent on computer '.'.
... error 1058 ...

L’erreur 1058 signifie que le service est désactivé — Windows ne démarre pas un service dont le type de démarrage est Disabled, et Start-Service ne le change pas pour vous. Corrigez d’abord le type de démarrage, puis démarrez-le (PowerShell avec privilèges élevés) :

Set-Service ssh-agent -StartupType Manual
Start-Service ssh-agent

Manual suffit pour le démarrer à la demande ; utilisez Automatic si vous le voulez actif à chaque démarrage. Si vous êtes sur une machine gérée ou dans un domaine, une stratégie de groupe l’a peut-être désactivé — dans ce cas, votre administrateur doit autoriser le service avant que cela ne tienne.

« error connecting to agent: No such file or directory »

Celle-ci vient du ssh de Git Bash / MSYS2, pas du service Windows. Elle signifie qu’on a indiqué à ssh où trouver le socket d’un agent — via SSH_AUTH_SOCK — et qu’il n’y a rien. Deux causes fréquentes :

Aucun agent ne tourne dans ce shell. Git Bash n’en démarre pas pour vous. Démarrez-en un dans le shell que vous utilisez :
```
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
```
Le eval a son importance : ssh-agent -s ne fait qu’afficher les variables ; c’est le eval qui les définit pour que ssh trouve le socket. Lancer ssh-agent tout seul et se demander pourquoi rien n’a changé, c’est le faux pas classique.
SSH_AUTH_SOCK est périmé. Une variable définie par une session précédente, un profil de connexion ou un autre outil pointe vers un socket qui n’existe plus. Vérifiez-la avec echo $SSH_AUTH_SOCK, puis soit supprimez-la et démarrez un agent neuf, soit corrigez-la pour qu’elle pointe vers un socket actif.

Si vous préférez utiliser le service Windows depuis Git Bash, appelez directement le binaire natif — /c/Windows/System32/OpenSSH/ssh.exe — au lieu du ssh MSYS2 présent dans votre PATH. Git Bash atteint alors les mêmes clés que vous avez chargées dans le service, et SSH_AUTH_SOCK n’a plus d’importance.

Les clés dans WSL

WSL est un système Linux distinct : il a donc son propre agent, son propre ~/.ssh et son propre SSH_AUTH_SOCK. Les clés chargées côté Windows ne sont pas visibles dans votre distribution, et inversement. Vous avez deux choix honnêtes :

Faites tourner un agent dans WSL, à la manière Linux habituelle — eval "$(ssh-agent -s)" et ssh-add, ou AddKeysToAgent yes dans le ~/.ssh/config de la distribution. Simple, totalement isolé, et couvert dans le guide ssh-add (en anglais).
Faites un pont vers l’agent Windows pour que les deux mondes partagent un seul magasin de clés. La recette habituelle relaie le canal nommé Windows vers un socket Unix vers lequel pointe le SSH_AUTH_SOCK de WSL, à l’aide de npiperelay.exe combiné à socat. Ça fonctionne bien une fois en place, mais ce sont des pièces mobiles en plus — n’y recourez que si vous avez vraiment besoin de la même clé des deux côtés.

Quel que soit votre choix, rappelez-vous que ssh-add -l dans WSL est une question différente de ssh-add -l dans PowerShell. Posez la bonne quand vous déboguez.

Quand l’agent va bien mais que la connexion échoue quand même

Si ssh-add -l affiche votre clé et que le serveur répond toujours Permission denied (publickey), l’agent a fait son travail — le problème est passé en aval : le authorized_keys du serveur, le mauvais utilisateur, ou la mauvaise clé proposée. C’est une autre liste de contrôle : Permission denied (publickey), corrigé dans l’ordre (en anglais). Et avant de transférer l’agent vers une machine distante avec ssh -A, lisez pourquoi le transfert d’agent est pratique et dangereux (en anglais) — il expose l’usage en direct de vos clés à l’autre bout.

Comment Termalin gère cela sous Windows

Si jongler avec des services, des sockets et trois magasins de clés dépasse ce à quoi vous voulez penser, c’est précisément le flux de travail que Termalin intègre. Il fait tourner son propre agent de clés sur un canal nommé Windows, \\.\pipe\termalin-ssh-agent, et sert les clés que vous avez déjà déverrouillées dans l’app via le protocole ssh-agent standard — un outil qui parle ce protocole peut ainsi signer à travers lui sans service système à activer, sans ligne eval, et sans ssh-add manuel. Les clés privées restent dans l’app en cours d’exécution et ne sont jamais écrites sur le disque. L’intérêt de cet agent est de permettre au serveur MCP de Termalin de s’authentifier auprès de vos serveurs avec vos clés sans jamais détenir le matériel de clé lui-même — l’agent signe, l’appelant ne voit jamais le secret. C’est la même idée de déverrouillage unique que le service OpenSSH, avec la configuration Windows en moins sur vos épaules.

Termalin est un client SSH gratuit et multiplateforme dont l’agent intégré déverrouille vos clés une fois et signe à votre place — téléchargez-le, ou lisez comment il gère vos clés en toute sécurité.