Concepts
A short tour of the ideas the rest of the docs rely on. Each section links the decision record behind it.
Vaults
Section titled “Vaults”A vault is a set of encrypted, write-once files that you keep in a git
repository (on its own vaultfold branch, or inside .vaultfold/ on a code
branch) or in a plain folder. Everything stored in
git or on a shared drive is ciphertext, so the storage never needs your
trust. Entries live in collections, and each collection has its own key.
See ADR 0004: write-once, content-addressed layout and ADR 0010: storage backends are dumb blob stores.
Members and devices
Section titled “Members and devices”A member is a person (or a machine). A member is a set of device keys, one per laptop, phone or token, so losing one device does not mean losing the account, and no private key is ever copied between devices. You add a teammate or a second machine by adding its public key, after comparing the fingerprint words out of band.
See ADR 0008: members are sets of device keys.
Epochs and revocation
Section titled “Epochs and revocation”Each collection key lives in an epoch. Adding a member is additive. Removing a
member, or a compromised device, mints a new epoch that the revoked key never receives, so
anything written afterwards is closed to them. What they already saw stays
seen, which is why revoking is followed by rotating the secrets they could
read (vaultfold rotate lists them).
Who is a member, which devices they have and what they may do is recorded on a policy chain: each change names the one before it, so nobody can slip a change in before something already recorded. A command that changes it publishes as it runs, and a revocation is final once it reports success.
See ADR 0007: membership changes are additive, revocation is a new epoch and ADR 0046: linear policy chain.
vault:// references
Section titled “vault:// references”A reference such as vault://app/db#password names one field of one entry.
You put references in env files, JSON, YAML or TOML, and vaultfold run
resolves them into a child process's environment, so the value is never
written to disk. AI coding agents may use references but are refused the
values themselves.