Skip to content

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.

  • 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.

Create an identity and export its public key. Send the file to an admin; it contains no secret.

Terminal window
vaultfold key new
vaultfold key show --public > me.pub

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.

Terminal window
vaultfold member add alice --from me.pub --role writer
vaultfold key verify alice
vaultfold member list

member 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.

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.

Terminal window
git clone git@example.com:acme/myapp.git
cd myapp
vaultfold vault add myapp . --branch vaultfold
vaultfold sync
vaultfold ls

If 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.

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.

Terminal window
vaultfold member grant hannes admin
vaultfold member ungrant alice writer --collection prod
vaultfold member rename alice Alicia

grant 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.

Terminal window
vaultfold member ungrant hannes admin

A 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.

  • Vault commands start the agent daemon and unlock once. Set VAULTFOLD_NO_AGENT=1 to 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-epoch chooses the earliest epoch the new member can read: first (the default) or current.
  • Hardware-resident device keys and machine identities are not available yet.