FAQ
Do I need Vaultwarden? No. Secrets live in an encrypted file on your machine by default. Vaultwarden (or the official Bitwarden cloud) is optional: use it to have the same secrets on several machines, or a copy on a server.
Do secrets leave my machine? Not with the local vault. With Vaultwarden or Bitwarden, only between
bw and your server; with a source,
only from that server to your machine. keyshroud has no backend of its own and sends no telemetry; values go into the
environment of the command you run.
I used keyshroud 0.7. What changes? Nothing. A machine with a bw login, keyshroud's files, wired
bw:// or !bw entries, BW_SESSION, or the master password in the keychain keeps Vaultwarden as the
default and writes that down in ~/.config/keyshroud/backend. Only a machine where none of these exist
looks new and gets the local vault; set KEYSHROUD_BACKEND=bw there if it should not.
How do I leave Vaultwarden? keyshroud migrate --to local: see
moving back to the local vault.
How do I back up the local vault? keyshroud backup writes one file sealed under a passphrase you
choose, and keyshroud restore FILE --yes brings its items and their wiring back on any machine
(Backup and restore). A plain copy of vault.json is not a backup: it opens only
with its key, which stays in this machine's key store. For the same secrets on several machines at
once, use Vaultwarden or Bitwarden.
Can a project get only its own secrets? Yes: keyshroud scope --only 'STRIPE_*,GH_TOKEN' in the
repo writes a .keyshroud.json that narrows run, env and what the agents are told there to those
names (Least privilege: a project's own names).
We use HashiCorp Vault (or AWS, 1Password, …) at work. Do I have to move the secrets? No. keyshroud reads them where they are: see team secret managers. It never writes to those systems, and what your account may read there is still decided by their policies.
Can I use it in CI or a Docker build? Yes, with a passphrase vault. Create it once in a terminal
(KEYSHROUD_VAULT_KEY=passphrase keyshroud unlock), add the secrets, and copy vault.json into the job
(it is encrypted, so it can live in the repository or an artifact). Keep only the passphrase in the CI's
secret store, then:
mkdir -p ~/.config/keyshroud && cp vault.json ~/.config/keyshroud/
printf '%s' "$KEYSHROUD_PASSPHRASE" | keyshroud unlock --stdin # a session of 30 minutes
keyshroud run --refs .env.refs -- npm test
--stdin only opens an existing passphrase vault; a new passphrase is always chosen in a terminal.
KEYSHROUD_PASSPHRASE is the name keyshroud knows the passphrase by: commands started by run do not
receive that variable, and its value is masked in their output. A
server you reach over SSH can instead run keyshroud unlock --unattended there once (no time limit).
The whole walk-through, with a GitHub Actions job and a Dockerfile, is in CI and Docker.
Can the agent still use the key? Yes. The command gets the real value; only the text the model reads is masked.
My program shows no prompt (or no colours) under keyshroud run. Since 0.13, run masks in a
terminal too, because some agents run commands on one, and masked output goes through a pipe. Give an
interactive program the terminal with --no-mask: keyshroud run --no-mask -- psql. Nothing it
prints is masked then, so that flag is for you, not for an agent's commands.
Is this a sandbox? No. It stops accidental disclosure. A hostile or prompt-injected agent can still exfiltrate a value it can use — see the security model.
Doesn't Claude Code do this itself? Partly, and differently. Claude Code can deny reads of
files such as .env (permissions.deny), strip credential-like variables from the processes it
starts (CLAUDE_CODE_SUBPROCESS_ENV_SCRUB), and its sandbox can show a command a placeholder for a
credential and put the real value on requests to hosts you allow (sandbox.credentials with
"mode": "mask": opt-in, for sandboxed Bash commands, and it needs the sandbox's TLS termination,
which Claude Code's documentation calls experimental). It has no secret store and does not rewrite
what a tool prints. keyshroud is the store, works the same across agents, covers secrets that are
not sent over HTTP (a database password, a signing key), and masks output. The two combine: the
sandbox for the credentials it can keep out of the shell, keyshroud for the rest. (As of Claude
Code's documentation on 2026-11-15.)
Why not just .gitignore my .env? That stops commits, not reads. Agents read .env
to debug, and whatever they read goes to the model provider.
Does it work on Windows? Yes, tested on Windows 10 with Node 22. The local vault keeps its key
with DPAPI, bound to your Windows account. bw and other npm CLIs (.cmd shims) run without a shell,
the unlock dialog is a small PowerShell window, and sessions end after 30 minutes like elsewhere. Files in
%USERPROFILE%\.config\keyshroud are protected by your profile's ACL (you, SYSTEM, Administrators), not
by 0600. One gap: over an SSH session with a terminal (ssh -t), Windows ends the lock timer when the
SSH session closes, so that session ends on the next keyshroud call instead. There is no keychain support
for the Vaultwarden master password on Windows: keyshroud asks for it (migrate too, in a terminal;
it is not tested there). pi auth.json entries of the !command form and the apiKeyHelper that
claude-setup writes need /bin/sh: for those, run keyshroud and the agent inside WSL (Git Bash beside
a native Windows Node is not enough).
DPAPI may be refused over SSH with a key (Access is denied): such a login carries no Windows
password. keyshroud says so; run the command in the desktop or RDP session, or give a machine used only
over SSH a passphrase vault (keyshroud rekey --to passphrase).
bw login prints KeyIdBackfillError? bw 2026.9 and later call an endpoint that Vaultwarden
added in 1.37.4 (vaultwarden#7750). The login
is saved anyway (bw status says locked), and keyshroud setup and the API-key login carry on by
themselves. Update Vaultwarden to 1.37.4 or later to make the error go away.