Skip to content

Paths

Four local directories, resolved in this order: VAULTFOLD_HOME (its config, data, cache and runtime subdirectories), then the absolute XDG variable on any OS, then the OS default.

Directory Linux and other unixes macOS Windows
Config ~/.config/vaultfold ~/Library/Application Support/vaultfold %APPDATA%\vaultfold
Data ~/.local/share/vaultfold ~/Library/Application Support/vaultfold %LOCALAPPDATA%\vaultfold
Cache ~/.cache/vaultfold ~/Library/Caches/vaultfold %LOCALAPPDATA%\vaultfold\cache
Runtime <Data>/runtime <Data>/runtime <Data>\runtime

What lives where:

  • Config: profile.toml (0600): identities, the vault registry ([vaults.<name>] with backend, location, directory, identity, auto-pull and staleness settings, file_cap), default_vault, default_identity, clipboard_clear_after.
  • Data: identities/<name>.key (identity files, 0600: sealed by a passphrase or by an OS keychain key; <name>-rotating.key only while key rotate runs), vaults/<name> (clones of remote vaults, kept here because they can hold unpushed events), the machine key that seals the local cache, the caller allowlist and the audit log's MAC key (machine.key.sealed, sealed by the Secure Enclave on macOS or DPAPI on Windows; a Secret Service item on Linux, recorded by the marker machine.key.secret-service; else the plain file machine.key), agent-trust.bin (the programs approved to use the daemon, sealed), audit/ (the daemon's audit log, agent.log and up to four rotated files), locks/ (per-vault lock files), audit.log (accepted rollbacks).
  • Cache: <vault-id>.bin per vault (sealed last-seen heads, remote commit and sync times; no keys, no plaintext; safe to delete, at the cost of restarting rollback detection) and ephemeral/ (records of inject --ephemeral files, for inject --wipe).
  • Runtime: the agent daemon's agent.sock (Linux and macOS; when that path is too long, vaultfold-<uid>/agent.sock under $TMPDIR or /tmp), agent.lock, agent.pid and agent.log (its output), notices/ (which terminals saw the in-process notice), and edit's temporary files (0600 in a 0700 directory, zero-overwritten and removed). On Windows the daemon listens on \\.\pipe\vaultfold-agent-<user SID>-<hash>, where <hash> is the first 16 hex characters of the SHA-256 of the lowercased runtime directory, so each profile gets its own pipe. A daemon a previous version left on the older SID-only pipe is stopped with vaultfold agent stop.

In a project, vault.toml at the repository root names the project's vault (default and [vaults.<name>] with backend and path). Two optional keys choose where an in-repo vault lives: branch = "vaultfold" puts it on that orphan branch (branch mode, the default for a new init; vault.toml is also at the root of that branch), and same_branch = true keeps it in .vaultfold/ on the checked-out branch. Setting both, an empty branch or a name git refuses is an error naming the file and key; a file with neither key is a vault from before branch mode and stays same-branch. An older vaultfold refuses a vault.toml or profile.toml with these keys and names the unknown key, which stops a teammate on an old version from syncing a copy of a vault the team moved.

A branch-mode registration in profile.toml also records branch, remote, path and, for a while after vault migrate of a vault committed on the code branch, legacy_path (the old vault directory, imported read-only until it is gone). Its dir is a mirror under <Data>/vaults/<name> that vaultfold owns, and its location is the repository's common git directory, so the checkout does not matter. The fetched branch is kept in the private ref refs/vaultfold/<remote>/<branch>, and an empty hooks directory under <Cache> is what keeps repository hooks from running. vaultfold vault remove deletes the mirror, the ref and the cache; nothing in the work tree or on the remote.