OmniSSHAgent

README

OmniSSHAgent

About

Unifies the chaotic ssh-agent state under Windows.

The Chaotic State of SSH-Agent on 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 Connection Diagram

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

System Requirements

• Windows 11
• Microsoft Edge WebView2

Supported Interfaces

• 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)

Usage

1. Download OmniSSHAgent-amd64-installer.exe from the 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-agent
Set-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 the OpenSSH Authentication Agent service, set Service Status to Stop, and Startup Type to Disabled.

1. If you are using PuTTY Pageant, stop it.

2. Launch OmniSSHAgent.exe by double-clicking it.

3. Press the Open new file button to add a private key file, or use the ssh-add command or KeePassXC to add your private key.

Registering for Startup

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

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

Using with WSL2

Setting up wsl2-ssh-agent-proxy in Ubuntu or Rocky (WSL2)

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.

Bash (and all POSIX-compliant shells)

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

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

1. 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

Fish

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

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

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

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

Using with WSL1

Setting up a Unix domain socket in the Ubuntu environment:

1. Check the setting for Unix 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.sock The 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

Using with Cygwin/MSYS2/Git for Windows (Git Bash)

1. Check the setting for Cygwin 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 the SSH_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.
   • In User variables, click New to create a new environment variable:

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

Using with OpenSSH ssh-agent NamedPipe (1Password, etc.) in Proxy Mode

This mode uses OpenSSH ssh-agent NamedPipe or 1Password's ssh-agent function as a backend, as shown in the diagram below.

By enabling "Proxy mode for 1Password key-agent" in the configuration, OmniSSHAgent functions as a proxy for 1Password or OpenSSH's NamedPipe SSH agent.

Note: When "Proxy mode for 1Password key-agent" is enabled, OmniSSHAgent operates solely as a proxy, meaning private keys cannot be added.

Supported Key File Formats

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

Supported Key Types

• RSA
• ECDSA
• ED25519

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

FAQ

Where is the passphrase for the private key stored?

Passphrases are stored in the Windows Credential Manager.

Screenshots