{"id":13548957,"url":"https://github.com/rupor-github/wsl-ssh-agent","last_synced_at":"2025-12-24T17:19:39.765Z","repository":{"id":38856852,"uuid":"206645976","full_name":"rupor-github/wsl-ssh-agent","owner":"rupor-github","description":"Helper to interface with Windows ssh-agent.exe service from Windows Subsystem for Linux (WSL)","archived":false,"fork":false,"pushed_at":"2025-03-29T20:32:13.000Z","size":1712,"stargazers_count":547,"open_issues_count":1,"forks_count":20,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-29T21:26:50.660Z","etag":null,"topics":["clipboard","lemonade","ssh","ssh-agent","ssh-agent-forwarding","sshagentwsl","windows-subsystem-linux","wsl","wsl-ssh"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rupor-github.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-05T19:52:44.000Z","updated_at":"2025-03-29T21:15:36.000Z","dependencies_parsed_at":"2024-06-18T21:52:54.121Z","dependency_job_id":null,"html_url":"https://github.com/rupor-github/wsl-ssh-agent","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rupor-github%2Fwsl-ssh-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rupor-github%2Fwsl-ssh-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rupor-github%2Fwsl-ssh-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rupor-github%2Fwsl-ssh-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rupor-github","download_url":"https://codeload.github.com/rupor-github/wsl-ssh-agent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246905096,"owners_count":20852809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clipboard","lemonade","ssh","ssh-agent","ssh-agent-forwarding","sshagentwsl","windows-subsystem-linux","wsl","wsl-ssh"],"created_at":"2024-08-01T12:01:16.489Z","updated_at":"2025-12-24T17:19:39.755Z","avatar_url":"https://github.com/rupor-github.png","language":"Go","readme":"\u003ch1\u003e\n    \u003cimg src=\"docs/ssh.svg\" style=\"vertical-align:middle; width:8%\" align=\"absmiddle\"/\u003e\n    \u003cspan style=\"vertical-align:middle;\"\u003e\u0026nbsp;\u0026nbsp;wsl-ssh-agent\u003c/span\u003e\n\u003c/h1\u003e\n\n# IMPORTANT NOTE ON PROJECT HISTORY\n\nThis project was started at the time when WSL2 did not exist and Microsoft just implemented AF_UNIX socket support. Today it is useful only when WSL1 is being required - which is really rare. Sharing Windows side ssh-agent with WSL2 does not need `wsl-ssh-agent.exe` at all! Please, read on next section on how to setup WSL2 and only continue after that if you really working with WSL1.\n\n## WSL2 compatibility\n\nAt the moment AF_UNIX interop does not seem to be working with WSL2 VMs. Hopefully this will be sorted out eventually. Meantime there is an easy workaround (proposed by multiple people) which does not use `wsl-ssh-agent.exe` and relies on combination of linux socat tool from your distribution and [npiperelay.exe](https://github.com/jstarks/npiperelay). *For example* put `npiperelay.exe` on drvfs for interop to work its magic (I have `winhome ⇒ /mnt/c/Users/rupor`, copy [wsl-ssh-agent-relay](docs/wsl-ssh-agent-relay) into your `~/.local/bin directory`, and add following 2 lines to your .bashrc/.zshrc file:\n\n```bash\n${HOME}/.local/bin/wsl-ssh-agent-relay start\nexport SSH_AUTH_SOCK=${HOME}/.ssh/wsl-ssh-agent.sock\n```\n\n**NOTE:** If you are having issues using `wsl-ssh-agent-relay` with systemd try adding `:WSLInterop:M::MZ::/init:PF` to `/usr/lib/binfmt.d/WSLInterop.conf`. For example (thanks to [rkl110](https://github.com/rkl110) - [Microsoft/WSL - Issue 8843](https://github.com/microsoft/WSL/issues/8843)):\n\n```bash\nsudo sh -c 'echo :WSLInterop:M::MZ::/init:PF \u003e /usr/lib/binfmt.d/WSLInterop.conf'\n```\n\nAlternatively if you prefer to directly use systemd support in WSL2 /etc/wsl.conf:\n\n```ini\n[boot]\nsystemd = true\n```\n\nyou could create wsl-ssh-agent.service unit in `/usr/lib/systemd/user`, something similar to:\n\n```ini\n[Unit]\nDescription=Windows SSH Agent Proxy via npiperelay\nStartLimitIntervalSec=0\n\n[Service]\nDelegate=true\nType=exec\nKillMode=process\nExecStart=/usr/bin/socat UNIX-LISTEN:'/run/user/\u003cuser id, usually 1000\u003e/wsl-ssh-agent.sock',fork EXEC:'/home/\u003cuser name\u003e/winhome/.wsl/npiperelay.exe -ei -s //./pipe/openssh-ssh-agent',nofork\n\n[Install]\nWantedBy=default.target\n```\n\nand then enable it:\n\n```bash\nsystemctl --user daemon-reload\nsystemctl --user enable --now wsl-ssh-agent.service\n\nexport SSH_AUTH_SOCK=${XDG_RUNTIME_DIR}/wsl-ssh-agent.sock\n```\n\nYou *really* have to be on WSL 2 in order for all of this to work - if you see errors like `Cannot open netlink socket: Protocol not supported` - you probably are under WSL 1 and should not use this workaround. Run `wsl.exe -l --all -v` to check what is going on. When on WSL 2 make sure that npiperelay.exe is on windows partition and path is right. For convenience I will be packing pre-build npiperelay.exe with wsl-ssh-agent. Please also ensure that `socat` is installed: `sudo apt install socat`.\n\n**NOTE:** You may be running Linux distribution with OpenSSH version more recent than your Windows host has out of the box. Presently Ubuntu 22.04 and Arch both demonstrate this - communication with ssh-agent will fail. In such cases please visit [Windows OpenSSH](https://github.com/PowerShell/Win32-OpenSSH) development and update your Windows OpenSSH with latest release.\n\n## Helper to interface with Windows ssh-agent.exe service from WSL1 (replacement for ssh-agent-wsl).\n[![GitHub Release](https://img.shields.io/github/release/rupor-github/wsl-ssh-agent.svg)](https://github.com/rupor-github/wsl-ssh-agent/releases)\n\nWindows has very convenient `ssh-agent` service (with support for persistence and Windows security). Unfortunately it is not accessible from WSL. This project aims to correct this situation by enabling access to SSH keys held by Windows own `ssh-agent` service from inside the [Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/about).\n\nMy first attempt - [ssh-agent-wsl](https://github.com/rupor-github/ssh-agent-wsl) was successful, but due to Windows interop restrictions it required elaborate life-time management on the WSL side. Starting with build 17063 (which was many updates ago) Windows implemented AF_UNIX sockets. This makes it possible to remove all trickery from WSL side greatly simplifying everything. \n\n**NOTE:** If you need access to more functionality (smard cards, identity management) provided by [GnuPG](https://www.gnupg.org/) set of tools on Windows or if you are looking for compatibility with wider set of utilities, like Git for Windows, Putty, Cygwin - you may want to take a look at [win-gpg-agent](https://github.com/rupor-github/win-gpg-agent) instead.\n\n`wsl-ssh-agent-gui.exe` is a simple \"notification tray\" applet which maintains AF_UNIX ssh-agent compatible socket on Windows end. It proxies all requests from this socket to ssh-agent.exe via named pipe. The only thing required on WSL end for it to work is to make sure that WSL `SSH_AGENT_SOCK` points to proper socket path. The same socket could be shared by any/all WSL sessions.\n\nAs an additional bonus `wsl-ssh-agent-gui.exe` could work as remote clipboard server so you could send your clipboard from tmux or neovim remote session back to your windows box over SSH secured connection easily. \n\n**NOTE: BREAKING CHANGE** Version 1.5.0 introduces breaking change. If you were not using `wsl-ssh-agent-gui.exe` as `lemonade` clipboard backend - this should not concern you at the slightest. Otherwise lemonade support no longer - it has been replaced with [gclpr](https://github.com/rupor-github/gclpr) which is more secure.\n\n**NOTE: BREAKING CHANGE** Version 1.6.0 introduces breaking change. If you were not using `wsl-ssh-agent-gui.exe` as `gclpr` clipboard backend - this should not concern you at the slightest. Otherwise starting with v1.1.0 gclpr server backend (included with v1.6.0) enforces protocol visioning and may require upgrade of gclpr tools.\n\n**SECURITY NOTICE:** All the usual security caveats applicable to WSL apply. Most importantly, all interaction with the Win32 world happens with the credentials of the user who started the WSL environment. In practice, *if you allow someone else to log in to your WSL environment remotely, they may be able to access the SSH keys stored in your ssh-agent.* This is a fundamental feature of WSL; if you are not sure of what you're doing, do not allow remote access to your WSL environment (i.e. by starting an SSH server).\n\n**COMPATIBILITY NOTICE:** `wsl-ssh-agent-gui` was tested on Windows 10 1903 with multiple distributions and should work on anything\nstarting with 1809 - beginning with insider build 17063 and would not work on older versions of Windows 10, because it requires\n[AF_UNIX socket support](https://devblogs.microsoft.com/commandline/af_unix-comes-to-windows/) feature.\n\n## Installation\n\n```\n    scoop install https://github.com/rupor-github/wsl-ssh-agent/releases/latest/download/wsl-ssh-agent.json\n```\nand updating:\n```\n    scoop update wsl-ssh-agent\n```\n\nAlternatively download from the [releases page](https://github.com/rupor-github/wsl-ssh-agent/releases) and unpack it in a convenient location.\n\nStarting with v1.5.1 releases are packed with zip and signed with [minisign](https://jedisct1.github.io/minisign/). Here is public key for verification:\n\n\u003cp\u003e\n    \u003cimg src=\"docs/build_key.svg\" style=\"vertical-align:middle; width:15%\" align=\"absmiddle\"/\u003e\n    \u003cspan style=\"vertical-align:middle;\"\u003e\u0026nbsp;\u0026nbsp;RWTNh1aN8DrXq26YRmWO3bPBx4m8jBATGXt4Z96DF4OVSzdCBmoAU+Vq\u003c/span\u003e\n\u003c/p\u003e\n\n## Usage\n\n1. Ensure that on Windows side `ssh-agent.exe` service (OpenSSH Authentication Agent) is started and has your keys. (After adding keys to Windows `ssh-agent.exe` you may remove them from your wsl home .ssh directory - just do not forget to adjust `IdentitiesOnly` directive in your ssh config accordingly. Keys are securely persisted in Windows registry, available for your account only). You may also want to switch its startup mode to \"automatic\". Using powershell with elevated privileges (admin mode):\n\n```powershell\n\tStart-Service ssh-agent\n\tSet-Service -StartupType Automatic ssh-agent\n```\n\n2. Run `wsl-ssh-agent-gui.exe` with arguments which make sense for your usage. Basically there are several ways:\n\n\t* Using `-socket` option specify \"well known\" path on Windows side and then properly specify the same path in every WSL session:\n\n\t\tWindows:\n\t\t    ```cmd\n\t\t\twsl-ssh-agent-gui.exe -socket c:\\wsl-ssh-agent\\ssh-agent.sock\n\t\t    ```\n\n\t\tWSL:\n\t\t    ```bash\n\t\t    export SSH_AUTH_SOCK=/mnt/c/wsl-ssh-agent/ssh-agent.sock\n\t\t    ```\n\n    * You could avoid any actions on WSL side by manually setting `SSH_AUTH_SOCK` and `WSLENV=SSH_AUTH_SOCK/up` on Windows side (**see note below**).\n\n\t* Using `-setenv` option allows application automatically modify user environment, so every WSL session started while\n      `wsl-ssh-agent-gui.exe` is running will have proper `SSH_AUTH_SOCK` available to it (using `WSLENV`). By default socket\n      path points to user temporary directory. Usual Windows user environment modification rules are applicable here (**see note below**).\n\n**NOTE:** Setting SSH_AUTH_SOCK environment on Windows side may (and probably will) interfere with some of Windows OpenSSH. As far as I could see presently utilities in `Windows\\System32\\OpenSSH` expect this environment variable to be either empty or set to proper `ssh-agent.exe` pipe, otherwise they cannot read socket:\n\n```\n\tif (getenv(\"SSH_AUTH_SOCK\") == NULL)\n\t\t_putenv(\"SSH_AUTH_SOCK=\\\\\\\\.\\\\pipe\\\\openssh-ssh-agent\");\n```\n\nTo avoid this and still be able to use `-setenv` and automatically generated socket path use `-envname` to specify variable name to set. Later on WSL side you could use:\n\n```bash\nexport SSH_AUTH_SOCK=${\u003c\u003cYOUR-NAME-HERE\u003e\u003e}\n```\n\nWhen `wsl-ssh-agent-gui.exe` is running you could see what it is connected to by clicking on its icon in notification tray area and selecting `About`. At the bottom of the message you would see something like:\n\n```terminal\nSocket path:\n  C:\\Users\\rupor\\AppData\\Local\\Temp\\ssh-273683143.sock\nPipe name:\n  \\\\.\\pipe\\openssh-ssh-agent\nRemote clipboard:\n  gclpr is serving 2 key(s) on port 2850\n```\n\nFor security reasons unless `-nolock` argument is specified program will refuse access to `ssh-agent.exe` pipe when user session is locked, so any long running background jobs in WSL which require ssh may fail.\n\n## Options\n\nRun `wsl-ssh-agent-gui.exe -help`\n\n```terminal\n---------------------------\nwsl-ssh-agent-gui\n---------------------------\n\nHelper to interface with Windows ssh-agent.exe service from WSL\n\nVersion:\n\t1.5.0 (go1.15.6)\n\nUsage:\n\twsl-ssh-agent-gui [options]\n\nOptions:\n\n  -debug\n    \tEnable verbose debug logging\n  -envname name\n    \tEnvironment variable name to hold socket path (default \"SSH_AUTH_SOCK\")\n  -help\n    \tShow help\n  -line-endings string\n    \tRemote clipboard convert line endings (LF/CRLF)\n  -nolock\n    \tProvide access to ss-agent.exe even when user session is locked\n  -pipe name\n    \tPipe name used by Windows ssh-agent.exe\n  -port int\n    \tRemote clipboard port (default 2850)\n  -setenv\n    \tExport environment variable with 'envname' and modify WSLENV\n  -socket path\n    \tAuth socket path (max 108 characters)\n```\n\n\n## Example\n\nPutting it all together nicely - `remote` here refers to your wsl shell or some other box or virtual machine you could `ssh` to.\n\nFor my WSL installations I always create `~/winhome` and link it to my Windows home directory (where I have `.wsl` directory with various interoperability tools from Windows side). I am assuming that [gclpr](https://github.com/rupor-github/gclpr) is in your path on `remote` and you installed it's Windows counterpart somewhere in `drvfs` location (~/winhome/.wsl is a good place).\n\nI auto-start `wsl-ssh-agent-gui.exe` on logon on my Windows box using following command line:\n\n```terminal\nwsl-ssh-agent-gui.exe -setenv -envname=WSL_AUTH_SOCK\n```\n\nIn my .bashrc I have:\n\n```bash\n[ -n ${WSL_AUTH_SOCK} ] \u0026\u0026 export SSH_AUTH_SOCK=${WSL_AUTH_SOCK}\n```\n\nand my `.ssh/config` entries used to `ssh` to `remote` have port forwarding enabled:\n\n```\nRemoteForward 2850 127.0.0.1:2850\n```\n\nOn `remote` my `tmux.conf` includes following lines:\n\n```tmux\nset -g set-clipboard off\nif-shell 'if [ -n ${WSL_DISTRO_NAME} ]; then true; else false; fi' \\\n  'bind-key -T copy-mode-vi Enter send-keys -X copy-pipe-and-cancel \"~/winhome/.wsl/gclpr.exe copy\" ; bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel \"~/winhome/.wsl/gclpr.exe copy\"' \\\n  'bind-key -T copy-mode-vi Enter send-keys -X copy-pipe-and-cancel \"gclpr copy\" ; bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel \"gclpr copy\"'\n```\n\nAnd my `neovim` configuration file `init.vim` on `remote` has following lines:\n\n```vim\nset clipboard+=unnamedplus\nif has(\"unix\")\n\t\" ----- on UNIX ask lemonade to translate line-endings\n\tif empty($WSL_DISTRO_NAME)\n\t\tif executable('gclpr')\n\t\t\tlet g:clipboard = {\n\t\t\t\t\\   'name': 'gclpr',\n\t\t\t\t\\   'copy': {\n\t\t\t\t\\      '+': 'gclpr copy',\n\t\t\t\t\\      '*': 'gclpr copy',\n\t\t\t\t\\    },\n\t\t\t\t\\   'paste': {\n\t\t\t\t\\      '+': 'gclpr paste --line-ending lf',\n\t\t\t\t\\      '*': 'gclpr paste --line-ending lf',\n\t\t\t\t\\   },\n\t\t\t\t\\   'cache_enabled': 0,\n\t\t\t\t\\ }\n\t\tendif\n\telse\n\t\t\" ---- we are inside WSL - reach out to the Windows side\n\t\tif executable($HOME . '/winhome/.wsl/gclpr.exe')\n\t\t\tlet g:clipboard = {\n\t\t\t\t\\   'name': 'gclpr',\n\t\t\t\t\\   'copy': {\n\t\t\t\t\\      '+': $HOME . '/winhome/.wsl/gclpr.exe copy',\n\t\t\t\t\\      '*': $HOME . '/winhome/.wsl/gclpr.exe copy',\n\t\t\t\t\\    },\n\t\t\t\t\\   'paste': {\n\t\t\t\t\\      '+': $HOME . '/winhome/.wsl/gclpr.exe paste --line-ending lf',\n\t\t\t\t\\      '*': $HOME . '/winhome/.wsl/gclpr.exe paste --line-ending lf',\n\t\t\t\t\\   },\n\t\t\t\t\\   'cache_enabled': 0,\n\t\t\t\t\\ }\n\t\tendif\n\tendif\nendif\n```\n\nNow you could open your WSL in terminal of your choice - mintty, cmd, Windows terminal, `ssh` to your `remote` using keys stored in Windows `ssh-agent.exe` without entering any additional passwords and have your clipboard content back on Windows transparently.\n\n## Credit\n\n* Thanks to [Ben Pye](https://github.com/benpye) with his [wsl-ssh-pageant](https://github.com/benpye/wsl-ssh-pageant) for inspiration.\n* Thanks to [Masataka Pocke Kuwabara](https://github.com/pocke) for [lemonade](https://github.com/lemonade-command/lemonade) - a remote utility tool. (copy, paste and open browser) over TCP.\n* Thanks to [John Starks](https://github.com/jstarks) for [npiperelay](https://github.com/jstarks/npiperelay) - access to Windows pipes from WSL.\n\n------------------------------------------------------------------------------\nLicensed under the GNU GPL version 3 or later, http://gnu.org/licenses/gpl.html\n\nThis is free software: you are free to change and redistribute it.\nThere is NO WARRANTY, to the extent permitted by law.\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frupor-github%2Fwsl-ssh-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frupor-github%2Fwsl-ssh-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frupor-github%2Fwsl-ssh-agent/lists"}