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.keyonly whilekey rotateruns),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 markermachine.key.secret-service; else the plain filemachine.key),agent-trust.bin(the programs approved to use the daemon, sealed),audit/(the daemon's audit log,agent.logand up to four rotated files),locks/(per-vault lock files),audit.log(accepted rollbacks). - Cache:
<vault-id>.binper vault (sealed last-seen heads, remote commit and sync times; no keys, no plaintext; safe to delete, at the cost of restarting rollback detection) andephemeral/(records ofinject --ephemeralfiles, forinject --wipe). - Runtime: the agent daemon's
agent.sock(Linux and macOS; when that path is too long,vaultfold-<uid>/agent.sockunder$TMPDIRor/tmp),agent.lock,agent.pidandagent.log(its output),notices/(which terminals saw the in-process notice), andedit'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 withvaultfold 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.