Skip to content

Concepts

A short tour of the ideas the rest of the docs rely on. Each section links the decision record behind it.

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.

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.

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.

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.

See ADR 0012: agent harness policy.