Repository files navigation

Unifies the chaotic ssh-agent state under Windows.

On Windows, there are multiple communication methods for SSH agents, leading to complexity in usage and configuration. The following diagram illustrates the current SSH agent communication landscape on Windows.

OmniSSHAgent simplifies this chaotic situation, as shown in the diagram below.

• Windows 11
• Microsoft Edge WebView2

• Pageant.exe (PuTTY) shared memory
• Unix domain socket for WSL2
• NamedPipe on Windows
• Unix domain socket for WSL1
• Unix domain socket for MSYS2 (Cygwin) (#1)

1. DownloadOmniSSHAgent-amd64-installer.exe fromthe latest release, and run the installer.
2. If you are using the native Windows SSH agent, you will need to stop and disable it. Open PowerShell with administrator privileges and run the following commands:

Stop-Service ssh-agentSet-Service-StartupType Disabled ssh-agent

• Alternatively, you can do this through the GUI: open the Start menu, type "Services," and select the Services app.Once open, find theOpenSSH Authentication Agent service, setService Status toStop, andStartup Type toDisabled.

3. If you are usingPuTTY Pageant, stop it.

4. LaunchOmniSSHAgent.exe by double-clicking it.

5. Press theOpen new file button to add a private key file, or use thessh-add command orKeePassXC to add your private key.

OmniSSHAgent does not have an installer to register itself for startup automatically. To add it manually:

• Press the Windows logo key + R, typeshell:startup, and click OK. This opens the Startup folder.
• Copy and paste a shortcut toOmniSSHAgent.exe into the Startup folder.

Choose the instructions for your preferred shell below. If your shell is not listed, you can convert the Bash script syntax and submit a pull request to add it to the repository.

1. Downloadubuntu.wsl2-ssh-agent-proxy.sh using the following command:

mkdir -p$HOME/wsl2-ssh-agent-proxycurl -sL https://raw.githubusercontent.com/masahide/OmniSSHAgent/refs/heads/main/hack/ubuntu.wsl2-ssh-agent-proxy.sh -o$HOME/wsl2-ssh-agent-proxy/ubuntu.wsl2-ssh-agent-proxy.sh

2. Add the following line to~/.bashrc,~/.zshrc, or the appropriate file for your shell:

source$HOME/wsl2-ssh-agent-proxy/ubuntu.wsl2-ssh-agent-proxy.sh

1. Downloadubuntu.wsl2-ssh-agent-proxy.fish using the following command:

mkdir-p$HOME/wsl2-ssh-agent-proxycurl-sL https://raw.githubusercontent.com/masahide/OmniSSHAgent/refs/heads/main/hack/ubuntu.wsl2-ssh-agent-proxy.fish-o$HOME/wsl2-ssh-agent-proxy/ubuntu.wsl2-ssh-agent-proxy.fish

2. Add the following line to~/.config/fish/config.fish:

.$HOME/wsl2-ssh-agent-proxy/ubuntu.wsl2-ssh-agent-proxy.fish

Setting up a Unix domain socket in the Ubuntu environment:

1. Check the setting forUnix domain socket file path (WSL1) in OmniSSHAgent.For example, if the path is set as follows (UserName will vary based on your environment):C:\Users\<UserName>\OmniSSHAgent.sockThe WSL1 path would be/mnt/c/Users/<UserName>/OmniSSHAgent.sock.

2. Add the following line to~/.bashrc:

export SSH_AUTH_SOCK=/mnt/c/Users/<UserName>/OmniSSHAgent.sock

1. Check the setting forCygwin Unix domain socket file path (MSYS2) in OmniSSHAgent.

   • For example, if the path is (UserName will vary based on your environment):
   • C:\Users\<UserName>\OmniSSHCygwin.sock
   • The Cygwin path would be/mnt/c/Users/<UserName>/OmniSSHCygwin.sock.

2. To set theSSH_AUTH_SOCK variable:

   • On the Windows taskbar, right-click the Windows icon and select System.
   • In the Settings window, under Related Settings, click Advanced system settings.
   • On the Advanced tab, click Environment Variables.
   • InUser variables, clickNew to create a new environment variable:

Variable name:  SSH_AUTH_SOCKVariable value: /mnt/c/Users/<UserName>/OmniSSHAgent.sock

This mode uses theOpenSSH ssh-agent NamedPipe as a backend. It can also be used with1Password’s ssh-agent function, as shown in the diagram below.

By enabling"Proxy mode for OpenSSH agent (also compatible with 1Password)" in the configuration, OmniSSHAgent functions as a proxy for Windows OpenSSH's NamedPipe SSH agent.
This mode also works with the 1Password key-agent.

Note: When "Proxy mode for OpenSSH agent (also compatible with 1Password)" is enabled, OmniSSHAgent operates solely as a proxy, and private keys cannot be added directly to it.

• PuTTY private key file (.ppk)
• OpenSSH format

• RSA
• ECDSA
• ED25519

(DSA, ECDSA-SK, ED25519-SK are not supported)

Passphrases are stored in theWindows Credential Manager.