Skip to content

Bitwarden

Jump to bottom
Mehdi edited this page Sep 2, 2026 · 1 revision

Bitwarden & Vaultwarden

SSH Pilot integrates with Bitwarden and Vaultwarden in two independent ways:

  1. Credential backend -- stores your SSH passwords and key passphrases
  2. Backup storage -- stores your configuration backups as secure notes

Both features use the same vault but work independently. You can use one without the other.

Important: It Is Slow by Design

Bitwarden/Vaultwarden integration is slower than local backends like the system keyring. This is not a bug -- it is inherent to how the Bitwarden CLI works:

  • Cold start: The bw CLI decrypts your entire vault on first access (~1-2 seconds)
  • rbw: Each lookup decrypts all entry names via agent IPC (~1 second)
  • Network sync: Vaultwarden or Bitwarden cloud may need to sync on unlock

SSH Pilot mitigates this by:

  • Caching decrypted secrets in memory after the first lookup
  • Pre-loading the vault on unlock so subsequent lookups are instant
  • Using the rbw-agent daemon to keep the vault warm between operations

If you have a large vault (thousands of items), expect the first operation after unlock to take a moment. Everything after that is fast.

Credential Backend

What it does

When you connect to a server and OpenSSH asks for a password or passphrase, SSH Pilot checks your Bitwarden vault. If a matching entry exists, the password is provided automatically.

Two options

Backend How it works Best for
Bitwarden (bw CLI) Official Bitwarden CLI Full-featured setup, large vaults
Bitwarden via rbw (rbw CLI) Lightweight agent-based alternative Simpler setup, faster agent-based lookups

Both talk to the same Bitwarden/Vaultwarden vault. They use the same vault folder (sshpilot) so entries created by one are visible to the other.

Choosing a backend

  1. Open Settings > Security
  2. Under Credential Backend, select Bitwarden / Vaultwarden or Bitwarden via rbw
  3. Follow the setup wizard to sign in

How credentials are stored

  • Each SSH connection's password is stored as a login item in your vault
  • Items are named after the connection's keyring account (e.g., root@192.168.1.50)
  • All items live in an sshpilot folder inside your vault, separate from your personal logins
  • The secret is stored in the login password field

First-time setup

  1. Select the Bitwarden backend in Settings > Security
  2. SSH Pilot will detect if the bw or rbw CLI is installed
  3. If not installed, you'll be offered an automatic download
  4. Sign in with your Bitwarden email and master password
  5. Complete two-factor authentication if enabled
  6. Unlock the vault

After setup, credentials are looked up automatically on each connection.

Backup Storage

What it does

You can save your SSH Pilot configuration backup (connections, settings, snippets, keys) directly to a Bitwarden secure note. This is separate from -- and in addition to -- the local file export.

How it works

  • Backups are stored as Bitwarden secure notes (not login items)
  • Each backup is a single note containing your entire configuration
  • You can have multiple backup notes (one per export)
  • Notes are prefixed with sshpilot_backup so they are easy to find

Creating a Bitwarden backup

  1. Open the application menu (hamburger menu on Linux, File menu on macOS)
  2. Go to Import/Export
  3. Click Export to Bitwarden
  4. Choose whether to include a passphrase (recommended)
  5. Confirm -- the backup is saved to your vault as a secure note

Restoring from a Bitwarden backup

  1. Open Import/Export
  2. Click Import from Bitwarden
  3. A list of available backups appears (sorted by date)
  4. Select a backup to preview its contents
  5. Confirm to restore

Size limit

Bitwarden secure notes have a maximum size. If your backup is too large (many private keys or a large SSH config), SSH Pilot will warn you and suggest which section is taking the most space. You can exclude private keys from the backup to reduce size.

rbw Backend

What is rbw?

rbw is a lightweight, agent-based CLI for Bitwarden/Vaultwarden. It is an alternative to the official bw CLI with a different architecture:

bw (official) rbw
Architecture Standalone CLI, spawns Node.js Persistent agent (rbw-agent)
Vault access Decrypts vault on each run Agent keeps vault warm in memory
Unlock bw unlock returns a session token rbw unlock passes password to agent via pinentry
Speed First lookup: ~1-2s (cold), subsequent: instant (cached) First lookup: ~1s (agent IPC), subsequent: instant (cached)
Dependencies Node.js (bundled with bw CLI) Rust binary, rbw-agent daemon

rbw setup

  1. Install rbw: cargo install rbw or use your package manager
  2. Configure rbw: rbw config set email you@example.com
  3. For Vaultwarden: rbw config set base_url https://vaultwarden.example.com
  4. Select Bitwarden via rbw in Settings > Security
  5. SSH Pilot will handle the unlock flow through its GTK dialog

How rbw unlock works

rbw has no built-in password flag -- it uses pinentry for password collection. SSH Pilot provides a custom one-shot pinentry helper that collects your master password through the GTK dialog and feeds it to rbw unlock. After unlock, rbw-agent holds the vault in memory and subsequent lookups are fast.

rbw caching

SSH Pilot caches rbw results to avoid repeated slow lookups:

  • Name cache: Item names in the sshpilot folder are cached for 30 seconds (one rbw list instead of many rbw get calls)
  • Value cache: Resolved secrets are cached for 5 minutes in the main process
  • Both caches are invalidated immediately when you store or delete a credential

Troubleshooting

"Bitwarden CLI not found"

Install the Bitwarden CLI:

"Vault is locked"

Unlock your vault:

  • SSH Pilot will prompt you for your master password
  • Or run bw unlock / rbw unlock in a terminal

"Login failed"

Check your email, master password, and two-factor code. For Vaultwarden, verify the server URL is correct in Settings.

Backups are slow

This is normal. Bitwarden secure notes require vault unlock and network sync. The first access after unlock may take a second or two.

Credentials not found

  • Ensure the backend is selected in Settings > Security
  • Check that the vault is unlocked
  • Verify the connection has a saved password (check the connection's Credentials tab)

Clone this wiki locally