Bitwarden SSH key picker

July 9, 2026 · View on GitHub

Servonaut can resolve a server's SSH private key straight from your Bitwarden Password Manager vault, so you never store the key on disk. Instead of pasting a vault item UUID by hand, you unlock your vault and pick the key from a list.

This is a local feature. The picker runs the bw CLI on your machine. Your master password and your vault contents never leave your computer — Servonaut's servers only ever store an opaque pointer (item_id) to the vault item, never the key itself.

Available on the Solo and Teams plans. Free-tier sessions see an upgrade card instead of the picker.

One-time setup

  1. Install the Bitwarden CLI (bw) and put it on your PATH: https://bitwarden.com/help/cli/

  2. Log in once, in your own terminal (this is the only step Servonaut does not drive — it involves your email, master password, and 2FA):

    bw login

    Servonaut detects whether you are logged in; it never handles bw login itself.

  3. Store your server keys as native SSH-key items in Bitwarden (BW 2023.10+). Servonaut reads the standard sshKey field — it does not look in notes or attachments.

Picking a key for a server

  1. Open a server's actions screen and choose Manage/Verify SSH Ref.
  2. Click Pick from vault….
  3. If your vault is locked, Servonaut prompts for your master password and unlocks it for the current session only (the session key is held in memory and discarded when you quit — you re-unlock on the next launch).
  4. Browse the list of SSH-key items, optionally typing in the search box, and select the one for this server.
  5. The reference is saved. The editor shows the item name (not the raw UUID).

The "Servonaut" folder

By default the picker lists only items in a Bitwarden folder named Servonaut, which it creates automatically the first time you use the picker. This keeps the list focused on server keys. Two ways to widen or change the scope:

  • Toggle "… folder only" off in the picker to browse your whole vault.
  • Change the folder name under Settings → Bitwarden SSH Vault → Vault folder. This is a local preference and does not affect the server-side vault wiring.

Advanced — paste a UUID

The editor keeps an Advanced section where you can paste an item UUID, collection ID, and vault URL directly — useful for items outside the Servonaut folder or power-user workflows. The collection ID and vault URL default to the values from your saved vault wiring, so you rarely need to re-enter them.

How resolution works on connect

When you SSH to a server that has a Bitwarden ref, Servonaut:

  1. Reads the stored item_id for that instance from the server-side pointer.
  2. Runs bw get item <item_id> locally, using the in-memory session from your unlock (falling back to an ambient BW_SESSION if you exported one by hand).
  3. Writes the resolved key to a temporary 0600 file for the SSH session.

The private key body is only ever read at connect time and is never rendered in the UI, written to a log, or sent anywhere.

MCP / headless resolution

The SSH-backed MCP tools (run_command, get_logs, get_server_info, transfer_file, and the incident-response probes) use the same chain: when an instance has a stored personal Bitwarden ref, the key is resolved from the vault and preferred over local ~/.ssh discovery. Requirements and behavior:

  • Ambient BW_SESSION required. The headless process has no unlock prompt — run bw unlock and export BW_SESSION in the environment the MCP server (or servonaut connect) runs in. If the vault is locked or the bw CLI is missing, the tool silently falls back to the local key, so a working local setup never breaks.
  • Personal refs only. Team-shared refs are not resolved on the headless surface yet.
  • Per-call temp key lifecycle. The resolved key is written to a 0600 file under ~/.servonaut/tmp/ immediately before the ssh/scp subprocess and deleted (zero-overwritten, then unlinked) as soon as it exits — the key never persists between tool calls.
  • Limitation: on servers that don't expose ref reads over the API, refs are read from a device-local mirror written when the ref was saved. A ref saved on another device resolves here only if the server exposes it.

Vault manager (fleet view)

The sidebar entry 🗝 BW SSH Vault opens a manager screen — the same "manager panel" shape the cloud providers have. It lists the SSH-key items in your Servonaut folder, joined with which servers reference each key and that server's last verify status (green = verified, red = failed, — = none).

From the manager you can:

  • Refresh (F5) — re-read the vault and re-compute the join.
  • Open in BW (o) — open the selected key in the Bitwarden web vault.
  • Manage ref (e) — open the SSH-ref editor for a server that references the selected key, so you can re-pick or clear it.
  • Import keys (a) — scan a local directory (default ~/.ssh) and upload keys into the vault. See below.

Like everything else here, the manager reads your vault locally; the server join uses only the opaque pointers Servonaut already stores.

Importing keys from ~/.ssh

Import keys (a) in the vault manager moves your existing local keys into the vault as native Bitwarden SSH items:

  1. Pick a directory. A picker opens rooted at your home directory, with ~/.ssh prefilled. Any directory works — hidden directories are shown.
  2. Review the scan. Servonaut scans the directory (non-recursive) for private-key files and lists each one with its type and fingerprint. Unencrypted keys are pre-selected; passphrase-protected keys show a 🔒 marker and are opt-in — tick each one you want to import.
  3. Passphrase prompts. For each selected encrypted key you are asked for its passphrase once, so the key can be decrypted for upload. A wrong passphrase just re-prompts; Skip leaves that key out. The passphrase is used in-memory only — it is never logged, written to disk, or passed to any command line.
  4. Import. Selected keys are created as SSH items in your Servonaut vault folder (or the folder name configured in Settings) and a vault sync runs so they appear on your other devices.

What to expect:

  • Vault encryption replaces the file passphrase. The imported copy is protected by your Bitwarden vault's encryption; the original file passphrase is not kept on the vault copy. Anyone who can unlock your vault can use the key — exactly like every other item in it.
  • Your original files are untouched. The import reads your key files; it never modifies or deletes them.
  • Keys are uploaded to your Bitwarden vault. The key material goes to wherever your vault lives (bitwarden.com or your self-hosted server), end-to- end encrypted by Bitwarden. Servonaut's own servers never see it.
  • Duplicates are skipped by fingerprint. A key whose SHA256 fingerprint already exists anywhere in your vault is shown as already in vault and is not created twice. If the vault listing fails during the scan (expired session, timeout), the import is blocked rather than risking duplicates — cancel and reopen the dialog to retry.
  • Unreadable or unsupported files are listed dimmed and skipped.

Settings

Settings → Bitwarden SSH Vault shows:

  • the current vault wiring (vault URL, default collection),
  • the local Vault folder name,
  • a live Bitwarden CLI status line (installed / logged in / locked / unlocked) with an Unlock now action.

Notes & limitations (v1)

  • Unlock only, not login. Servonaut handles bw unlock; the one-time bw login stays a manual shell step.
  • SSH-key items only. Username/password login items are a planned follow-up.
  • Session is in-memory only. A "remember on this device" option is planned but not yet available.