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 serverbelow (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 ownbwlogin is untouched. Its master password is not stored: keyshroud asks for it when a session ends and keeps only a scrypt hash, soaddcan refuse it as a secret. migratecopies 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 entryvaultwarden-master-password).- An agent can run
setuptoo. 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 runssetup --registered, which asks for it in a dialog. The password never passes through anything the agent can read.--confirm-unlockand--unattendedneed a terminal. --confirm-unlock(macOS) stores the master password in the keychain entrykeyshroud-master-passwordso 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. overssh -t) logs in with a session without an end. Unlock it again withkeyshroud 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--registeredonce 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.