Add a teammate or a device
Membership is additive: you add a public key and check its fingerprint with its owner. Nothing is re-encrypted and the new member never needs your private key.
Prerequisites
Section titled “Prerequisites”- You are an admin of the vault.
- The vault is in a git repository with a remote that both machines can reach (see sync and conflicts). Membership commands publish to it as they run, so it must be reachable when you run them.
- A way to compare a few words with the other person out of band, in person or on a call.
On the new machine
Section titled “On the new machine”Create an identity and export its public key. Send the file to an admin; it contains no secret.
vaultfold key newvaultfold key show --public > me.pubOn a machine that has the vault
Section titled “On a machine that has the vault”Add the key, choosing a role. The default is reader; writer, rotator and
admin are the others. member add shows the fingerprint words of the key.
Compare them with the owner before you confirm. The command pulls first,
records the change and publishes it before it returns, so there is nothing to
sync afterwards; without the remote it writes nothing and exits 4.
vaultfold member add alice --from me.pub --role writervaultfold key verify alicevaultfold member listmember add also prints a chain fingerprint: a link number and eight words,
such as 57- followed by the words. Give it to the new member out of band
along with the fingerprint check; it lets their machine refuse a remote that
shows it a different membership history.
A second machine of your own is added the same way, as a member of its own
(for example alice-laptop). You can also fetch keys from a GitHub user with
--github <user>, or from an https URL with --from; those sources always ask
you to confirm each key.
Back on the new machine
Section titled “Back on the new machine”Clone the repository, register its vault, and read something. Running any
vault command in the clone offers to register the vault. To do it by hand, use
the vault name that is in the repository's vault.toml (the name the creator
registered, myapp here); another name registers but then ls fails because
vault.toml names a vault that is not registered. The vault lives on the
vaultfold branch, so name it with --branch.
git clone git@example.com:acme/myapp.gitcd myappvaultfold vault add myapp . --branch vaultfoldvaultfold syncvaultfold lsIf the admin gave you a chain fingerprint, add --expect-head <fingerprint>
to vault add: it then exits 2 with expect-head-mismatch and registers
nothing when the vault's policy chain does not hold the link the admin named.
Registering does not make the machine a member. Until an admin has added its
key, sync on the new machine says the device is not a member yet
and shows the key show --public step. A vault kept on a code branch with
init --same-branch registers with vaultfold vault add myapp ./.vaultfold
instead.
A reader can read but not write; a write is refused until an admin grants a
writer role. vaultfold device list and vaultfold epoch list show who holds
which key.
Change a role or a name
Section titled “Change a role or a name”You do not need to remove a member and add them again to change what they can
do. Run these on a machine of an admin; like member add, each one pulls,
records and publishes in the command, so the remote must be reachable. They are
refused in an AI agent session.
vaultfold member grant hannes adminvaultfold member ungrant alice writer --collection prodvaultfold member rename alice Aliciagrant takes a role on a collection (--collection, default the root
collection) and wraps the epoch keys it gives. Root admins are peers: any root
admin can remove another root admin's admin role at once, and any can grant
it back.
vaultfold member ungrant hannes adminA removal is final once the command reports it published; another root admin
can grant the role back. A demoted admin keeps the keys it already holds; member revoke is what cuts
off reading. A member can rename itself. Names are labels, not proof
of identity: member list shows who set each name, and key verify is how
you check who someone is.
Current limitations
Section titled “Current limitations”- Vault commands start the agent daemon and unlock once. Set
VAULTFOLD_NO_AGENT=1to skip the daemon and unlock in-process for that command only. - A key can be registered once in a vault; adding the same public key under a second name is refused.
--from-epochchooses the earliest epoch the new member can read:first(the default) orcurrent.- Hardware-resident device keys and machine identities are not available yet.