keyshroud

Sync across machines: Vaultwarden or Bitwarden

Keep the secrets in Vaultwarden or Bitwarden instead to have them on several machines; run, the hooks, the MCP server and everything else work the same, through the Bitwarden CLI.

Get a vault — pick one:

  • Self-host Vaultwarden (free, your server): follow examples/vaultwarden — Docker Compose + Caddy with automatic HTTPS, from an empty VPS to keyshroud doctor, plus backups and hardening.
  • Bitwarden cloud (free account, no server): sign up at bitwarden.com and skip bw config server below (EU accounts: bw config server https://vault.bitwarden.eu).
npm install -g @bitwarden/cli

# 1. Point bw at your server and log in once
bw config server https://vault.example.com
bw login

# 2. Make it the default for new items (keyshroud:// items keep working)
mkdir -p ~/.config/keyshroud && echo bw > ~/.config/keyshroud/backend

# 3. Unlock for 30 minutes (asks for the master password, which is not stored)
keyshroud unlock

# 4. Check everything
keyshroud doctor

keyshroud picks the default once per machine and writes it to ~/.config/keyshroud/backend: Vaultwarden when it finds a bw login or anything keyshroud 0.7 left behind, so upgrades change nothing; the local vault otherwise. KEYSHROUD_BACKEND=local|bw overrides it, and keyshroud setup switches to Vaultwarden by itself. References name their vault, so keyshroud://… and bw://… items work side by side, and --item keyshroud://Name or --item bw://Name picks one for a single item.

keyshroud never stores the master password unless you do. When Vaultwarden is locked and a command needs a secret, it asks: a masked prompt in a terminal, a native dialog on the desktop (so an agent's command waits for you), and over SSH it tells you to run keyshroud unlock. A session ends after 30 minutes (KEYSHROUD_SESSION_TTL_MS): a timer runs bw lock, so a copied session token stops working too. On a host nobody sits at, keyshroud unlock --unattended asks once, in a terminal only, and opens a session without an end.

To unlock without being asked, store the master password in the OS keychain (security add-generic-password -a "$USER" -s vaultwarden-master-password -w, or secret-tool store on Linux; after setup the entry is keyshroud-master-password; see the vault setup guide). Any program running as you can then read it, agents included. Windows has no keychain support for it.

Least privilege: a separate agent account

With the steps above, an unlocked session opens your whole Vaultwarden vault, and an agent that runs bw as you can use it. setup gives keyshroud its own bw login on a dedicated account instead, which holds only the secrets agents need:

keyshroud setup --email you+agent@example.com   # opens the signup page, then logs in with the
                                                 # new master password (asked, not stored);
                                                 # no `bw config server`: Bitwarden cloud
keyshroud migrate                                # dry run: which wired items would be copied
keyshroud migrate --yes                          # copy them; references keep working
  • The agent login lives in ~/.config/keyshroud/bw (BITWARDENCLI_APPDATA_DIR). Your own bw login is untouched. Its master password is not stored: keyshroud asks for it when a session ends and keeps only a scrypt hash, so add can refuse it as a secret.
  • migrate copies the items that wired names (and any --refs / --item) reference, with the same names, then locks your personal vault again. Originals stay where they are. It asks for your personal master password in a terminal (or reads the keychain entry vaultwarden-master-password).
  • An agent can run setup too. Without a terminal it opens the signup page, where you pick the agent account's master password yourself (save it in your password manager); then the agent runs setup --registered, which asks for it in a dialog. The password never passes through anything the agent can read. --confirm-unlock and --unattended need a terminal.
  • --confirm-unlock (macOS) stores the master password in the keychain entry keyshroud-master-password so that macOS asks you before every read, i.e. every unlock.
  • If bw loses the login (a rejected refresh token logs it out), keyshroud on a Mac with the master password in the keychain asks for Touch ID and logs the agent account back in.
  • --unattended (hosts nobody sits at, e.g. over ssh -t) logs in with a session without an end. Unlock it again with keyshroud unlock --unattended.
  • Self-hosted Vaultwarden with SIGNUPS_ALLOWED=false: invite the address from the admin page (/admin), or allow signups for a minute, then pass --registered once the account exists.

Moving back to the local vault

keyshroud migrate --to local shows which Vaultwarden items your wired names use; --yes copies them into the local vault, checks each copy, rewires the names and makes the local vault the default for new items. A field other than the password becomes an item of its own (Sentry (field dsn)). Vaultwarden keeps the originals, the previous references are saved next to the vault (names and references only), and .env.refs files keep their bw:// references until you change them. Other machines that use the same Vaultwarden are not affected.

Edit this page on GitHub · Markdown