Skip to content

Instantly share code, notes, and snippets.

@eliottness
Last active November 17, 2026 02:00
Show Gist options
  • Select an option

  • Save eliottness/f144341ee3952493468dcab94da66313 to your computer and use it in GitHub Desktop.

Select an option

Save eliottness/f144341ee3952493468dcab94da66313 to your computer and use it in GitHub Desktop.
Bitwarden SSH agent in WSL2 via a systemd user service (socat + npiperelay) — with the gotchas that make ssh-add hang

Bitwarden SSH agent in WSL2 (via systemd)

Use the SSH keys stored in your Windows Bitwarden Desktop vault from inside WSL2 — ssh, git, ssh-add, etc. — managed by a systemd user service instead of a fragile .zshrc snippet.

This bridges the Windows OpenSSH-agent named pipe that Bitwarden exposes (\\.\pipe\openssh-ssh-agent) to a Unix socket inside WSL using npiperelay + socat.

It is a hardened version of the excellent walkthrough at https://www.rebelpeon.com/bitwarden-ssh-agent-on-wsl2/, with fixes for the problems that make ssh-add -l hang.


TL;DR

Windows                                   │ WSL2
                                          │
Bitwarden Desktop (standalone build)      │
  └─ \\.\pipe\openssh-ssh-agent  ◀────────┼──  npiperelay.exe  ◀──  socat  ◀──  ~/.ssh/agent.sock
       (one pipe instance)                │      (per connection)   (listener)     ▲
                                          │                                         │
                                          │                       ssh / git / ssh-add (SSH_AUTH_SOCK)

A systemd user service runs one persistent socat listener. socat forks a short-lived npiperelay.exe for each incoming connection, which relays bytes to Bitwarden's named pipe.


Prerequisites (the part everyone gets wrong)

1. Use the STANDALONE Bitwarden build — NOT the Microsoft Store version

The Microsoft Store / Appx build of Bitwarden Desktop runs in a UWP AppContainer sandbox and does not serve the SSH agent to external clients. The pipe appears and connections open, but Bitwarden never replies — so everything hangs, including the native Windows ssh-add.exe.

Check what you have (PowerShell):

Get-AppxPackage *Bitwarden*      # if this prints anything, you have the Store build — uninstall it

Fix — remove the Store/Appx build, then install the standalone build:

# Remove the Store (Appx) build. winget can't uninstall it by that name, so use Appx:
Get-AppxPackage *Bitwarden* | Remove-AppxPackage

# Install the standalone build (validated winget id):
winget install Bitwarden.Bitwarden

Or download the desktop installer from https://bitwarden.com/download/.

2. Enable the agent in Bitwarden

Bitwarden → Settings → SSH agent → Enable SSH agent. Have at least one SSH key item in your vault, and keep the vault unlocked (the agent only answers while unlocked).

3. Disable the Windows OpenSSH agent service (avoid pipe conflicts)

It would fight Bitwarden for the same pipe name. PowerShell (admin):

Stop-Service ssh-agent
Set-Service ssh-agent -StartupType Disabled

4. WSL prerequisites

  • WSL2 with systemd enabled — /etc/wsl.conf:
    [boot]
    systemd=true
    (then wsl --shutdown from Windows once)
  • socat installed: sudo apt install socat
  • npiperelay.exe on the Windows side. Easiest:
    winget install albertony.npiperelay
    then find the path (it lives under C:\Users\<you>\AppData\Local\Microsoft\WinGet\Packages\albertony.npiperelay_*\npiperelay.exe).
  • Enable lingering so the service runs without an interactive login:
    loginctl enable-linger "$USER"

Install

  1. Find your npiperelay path and put it in bw-ssh-relay (edit the NPIPERELAY= line). From WSL:

    ls /mnt/c/Users/*/AppData/Local/Microsoft/WinGet/Packages/albertony.npiperelay_*/npiperelay.exe
  2. Install the relay script:

    mkdir -p ~/.local/bin
    cp bw-ssh-relay ~/.local/bin/bw-ssh-relay
    chmod +x ~/.local/bin/bw-ssh-relay
  3. Install the service:

    mkdir -p ~/.config/systemd/user
    cp bitwarden-ssh-agent.service ~/.config/systemd/user/
    systemctl --user daemon-reload
    systemctl --user enable --now bitwarden-ssh-agent.service
  4. Point your shell at the socket. Add to ~/.bashrc / ~/.zshrc:

    export SSH_AUTH_SOCK="$HOME/.ssh/agent.sock"
  5. Test (open a new shell):

    ssh-add -l        # should list your Bitwarden SSH key(s)

Files

File Goes to Purpose
bw-ssh-relay ~/.local/bin/bw-ssh-relay Launches the socat ↔ npiperelay bridge (the service's ExecStart).
bitwarden-ssh-agent.service ~/.config/systemd/user/ systemd user unit that keeps one relay listener running and restarts it on failure.

npiperelay flags used

This is the upstream-article command: -ei -s — nothing more.

Flag Meaning
-ei Terminate when the client (stdin) closes — clean teardown per connection. This is what prevents process leaks, so it must be able to fire.
-s Send a 0-byte message after EOF (part of the original recipe).

⚠️ Do NOT add -p. It seems helpful ("poll until the pipe is free") but it is a trap with Bitwarden. Bitwarden exposes only one pipe instance; when it is busy or wedged, -p makes npiperelay loop forever in DialPipe. While polling it never reads stdin, so -ei can never fire on disconnect — and the Windows npiperelay.exe leaks under wslhost, one orphan per ssh/git operation, until you kill them by hand. Without -p, a busy pipe just makes the connection fail fast (retryable). See the troubleshooting note below.


Why systemd instead of .zshrc

The common .zshrc approach has every shell try to start/manage its own socat. That causes:

  • Races between shells spawning competing listeners.
  • Hangs at shell startup if the block probes the agent with ssh-add -l while Bitwarden's single pipe instance is busy — the new terminal blocks forever.
  • Orphaned npiperelay.exe processes left behind by closed terminals.

A single systemd user service owns exactly one listener, survives across all terminals, restarts on failure, and starts on boot (with linger).


Gotchas & troubleshooting

ssh-add -l hangs or says "communication with agent failed"

Figure out which side is broken. The native Windows client talks straight to the pipe — no WSL, socat, or npiperelay involved:

/mnt/c/Windows/System32/OpenSSH/ssh-add.exe -l
  • It also hangs/fails → the problem is Bitwarden, not WSL. See below.
  • It works but WSL doesn't → the problem is the relay (socat/npiperelay path, flags, or socket). Check journalctl --user -u bitwarden-ssh-agent.

Bitwarden's agent "wedges" (worked once, then hangs for everyone)

Bitwarden exposes a single pipe instance. If a client connection is interrupted or force-killed — a closed terminal mid-operation, a Ctrl-C'd ssh-add, or Stop-Process -Force on npiperelay.exe — Bitwarden may fail to re-arm the listener. After that, every client (including native ssh-add.exe) hangs until you kick the agent:

  1. Bitwarden → Settings → SSH agent → toggle off, then on; or
  2. Fully quit Bitwarden (tray → Quit) and reopen + unlock.

This is why this unit deliberately does not force-kill orphaned npiperelay.exe — abruptly killing an in-flight pipe client is one of the things that wedges the agent.

If orphaned npiperelay.exe ever genuinely pile up, clear them by hand (PowerShell):

Get-Process npiperelay -ErrorAction SilentlyContinue | Stop-Process -Force

All pipe instances are busy

This means another client momentarily holds Bitwarden's single pipe instance, or the agent is wedged. Do not "fix" it with -p — that trades a fast, retryable error for an unbounded orphan leak (see the flags note above). Instead:

  • If it's transient (two ssh ops at once), just retry.
  • If it persists with nothing connected, the agent is wedged — kick Bitwarden (toggle the SSH agent setting, or fully quit + reopen).
  • If you see orphaned npiperelay.exe piling up, you almost certainly have -p somewhere — remove it.

Service won't run the .exe ("interop")

systemd user services can normally launch Windows .exe files in recent WSL. Verify:

systemd-run --user --wait --pipe /path/to/npiperelay.exe -h

If that fails, your WSL build may not expose interop to systemd services; update WSL (wsl --update).


Managing the service

systemctl --user status   bitwarden-ssh-agent
systemctl --user restart  bitwarden-ssh-agent
systemctl --user stop     bitwarden-ssh-agent
journalctl  --user -u     bitwarden-ssh-agent -f

Credits

[Unit]
Description=Bitwarden SSH agent bridge (Windows named pipe -> WSL2 unix socket)
Documentation=https://www.rebelpeon.com/bitwarden-ssh-agent-on-wsl2/
After=default.target
[Service]
Type=simple
Environment=SSH_AUTH_SOCK=%h/.ssh/agent.sock
# Drop a stale socket so socat can bind cleanly. We deliberately do NOT
# force-kill orphaned npiperelay.exe here: abruptly killing an in-flight pipe
# client can wedge Bitwarden's single-instance agent. If orphans ever pile up,
# clear them by hand (see the relay script header).
ExecStartPre=-/bin/sh -c 'rm -f "%h/.ssh/agent.sock"'
ExecStart=%h/.local/bin/bw-ssh-relay
Restart=on-failure
RestartSec=2
[Install]
WantedBy=default.target
#!/usr/bin/env bash
# Bitwarden SSH agent relay: bridge the Windows OpenSSH-agent named pipe to a
# WSL2 unix socket so ssh/ssh-add inside WSL use Bitwarden's keys.
# Managed by the systemd --user unit bitwarden-ssh-agent.service.
set -u
SOCK="${SSH_AUTH_SOCK:-$HOME/.ssh/agent.sock}"
# Path to npiperelay.exe on the Windows side. Either hardcode it, e.g.
# NPIPERELAY="/mnt/c/Users/<YOUR_WINDOWS_USER>/AppData/Local/Microsoft/WinGet/Packages/albertony.npiperelay_Microsoft.Winget.Source_8wekyb3d8bbwe/npiperelay.exe"
# or let it auto-detect the winget-installed copy across user profiles:
NPIPERELAY="$(ls /mnt/c/Users/*/AppData/Local/Microsoft/WinGet/Packages/albertony.npiperelay_*/npiperelay.exe 2>/dev/null | head -n1)"
PIPE="//./pipe/openssh-ssh-agent"
if [ -z "${NPIPERELAY}" ] || [ ! -x "${NPIPERELAY}" ]; then
echo "bw-ssh-relay: npiperelay.exe not found; set NPIPERELAY in this script." >&2
exit 1
fi
# socat forks one npiperelay per incoming connection. -ei makes npiperelay exit
# when the client disconnects, so each connection cleans itself up.
#
# DO NOT add -p (poll-until-free). Bitwarden exposes only ONE pipe instance, and
# with -p npiperelay loops forever in DialPipe whenever that instance is busy or
# the agent is wedged. While polling it never reads stdin, so -ei can't fire on
# disconnect, and the Windows process leaks under wslhost — one orphan per
# ssh/git operation. Failing fast on a rare busy collision (retryable) is far
# better than an unbounded orphan leak.
exec socat "UNIX-LISTEN:${SOCK},fork" \
EXEC:"${NPIPERELAY} -ei -s ${PIPE}",nofork
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment