bw-ssh-agent

bw-ssh-agent is a lightweight SSH agent that uses your Bitwarden SSH keys.

It supports email-based 2FA during login and custom Bitwarden server endpoints.

This project is unofficial and is not affiliated with or endorsed by Bitwarden.

Requirements

• Linux
• Secret Service (usually already available on most Linux desktop setups)

Quick Start

1. Install bw-ssh-agent (choose one method):

   Install manually (download binary)

   1. Download the release binary for your system (bw-ssh-agent-(os)-(arch)).

   2. Move it to $HOME/.local/bin and rename it to bw-ssh-agent:

      mkdir -p "$HOME/.local/bin"
      mv /path/to/downloaded/binary "$HOME/.local/bin/bw-ssh-agent"
      chmod +x "$HOME/.local/bin/bw-ssh-agent"

   Make sure $HOME/.local/bin is in your PATH. If bw-ssh-agent is not found, restart your shell or run:

   export PATH="$HOME/.local/bin:$PATH"

   Install with mise

   mise use -g github:flipper/bw-ssh-agent

2. Log in:

   bw-ssh-agent login

3. Set up background service (systemd, recommended):

   bw-ssh-agent install

   Other init systems

   Configure your init/service manager to run this in the background:

   bw-ssh-agent agent

4. Reboot to apply all changes.

Commands

bw-ssh-agent login

Log in to Bitwarden, including email-based 2FA.

Optional flags:

• --email <email>
• --password <password>
• --identity-url <url>
• --api-url <url>

bw-ssh-agent status

Show login status.

bw-ssh-agent agent

Run the SSH agent (this is what your service manager should run in the background).

Optional flag:

• --sync-interval <seconds> (default: 1800)

bw-ssh-agent install

Automatic setup for systemd: installs and starts bw-ssh-agent as a user service.

After running install, reboot your system to apply all changes.

bw-ssh-agent uninstall

Remove the installed user service setup.

Custom Bitwarden Endpoints

Use custom servers with:

bw-ssh-agent login --identity-url <identity-url> --api-url <api-url>

Bitwarden EU example

bw-ssh-agent login \
  --identity-url https://vault.bitwarden.eu/identity/ \
  --api-url https://vault.bitwarden.eu/api/

Notes

• Socket path: $XDG_RUNTIME_DIR/bw-ssh-agent.sock