Skip to content

Filesystem

dotvault can mount your Vault secrets as a filesystem. Each secret becomes a .json file whose contents are its data section, and each KV folder becomes a directory:

$ ls ~/.dotvault
databricks  gh.json  jfrog.json

$ jq . ~/.dotvault/gh.json
{
  "oauth_token": "gho_...",
  "user": "gary"
}

$ jq -r .oauth_token ~/.dotvault/gh.json | gh auth login --with-token

The extension is not decoration: the contents really are JSON, and it is what makes an editor, an IDE or vim highlight, fold and lint the file instead of treating it as unknown plain text. Directories carry no extension — a KV folder is not a JSON document.

It is disabled by default. Where sync rules write specific fields into specific config files on a schedule, the filesystem is the opposite: a live, read-only view of everything under your own KV prefix, for the cases where writing a rule is more ceremony than the job deserves — a one-off script, an interactive shell, a tool that wants a value you have not templated anywhere.

Enabling it

In the system configuration (see the config reference for its path on each platform):

fuse:
  enabled: true
  mountpoint: "~/.dotvault"   # default
  read_write: false           # default
  cache_ttl: "30s"            # default

The daemon mounts the filesystem after its first successful Vault authentication and unmounts it on shutdown. The mountpoint is created (mode 0700) if it does not exist.

dotvault status reports what is configured and whether anything is actually mounted:

$ dotvault status
...
Filesystem:
  mountpoint:  /home/gary/.dotvault
  mode:        read-only
  cache ttl:   30s
  state:       mounted

(A preferences: line appears when a per-user file contributed to the section.)

Per-user preferences

The fuse section can also be set in your own configuration file, which is merged over the system configuration:

Platform Path
Linux ${XDG_CONFIG_HOME:-~/.config}/dotvault/config.yaml
macOS ~/Library/Application Support/dotvault/config.yaml
Windows %APPDATA%\dotvault\config.yaml
# ~/.config/dotvault/config.yaml
fuse:
  enabled: true
  mountpoint: "~/vault"
  cache_ttl: "5s"

This is the file to use when your machine's system configuration does not mention the filesystem and you want it, without editing a config an administrator owns.

Only fuse may appear here. Any other section — vault, web, agent, api, and the rest — is a hard error naming it, because that file is yours to write and configuration like where the daemon points its Vault is not. A section this build does not recognise is ignored with a warning, so a newer dotvault's config still starts on an older binary.

Each field merges by its own rule rather than simply overwriting policy:

Field Rule
enabled You may turn the filesystem on when the system leaves it off. You may not turn it off when the system enables it
read_write You may turn writes off when the system enables them. You may not turn them on
mountpoint Yours wins
cache_ttl Yours wins

The two booleans ratchet in opposite directions, and that is deliberate rather than an inconsistency. Enabling a read-only mount grants nothing your Vault token could not already do, so an administrator's "off" is only a default. Read-write is a different kind of setting — it puts every process running as you one > away from replacing a credential — so there the administrator's "no" is binding, and you stay free to be more careful than policy requires.

The ratchet expresses intent; it is not a security control

mountpoint is not ratcheted, so a user who wants no mount can point it somewhere that cannot be mounted and get one — a failed mount is logged and not retried. That is not a hole worth closing: anyone who can run fusermount3 -u on their own session can unmount it anyway, and a per-user daemon runs as them. What the ratchet does is stop opting out being a silent, supported gesture in a config file, and make the intent explicit on both sides. An administrator who needs the filesystem to be genuinely unavoidable needs something other than this file.

An omitted key is not a preference. Writing only mountpoint: leaves enabled and read_write exactly as the system configuration set them; you have to write enabled: false to mean it, and even then it only takes effect if the system had not already enabled it. When a preference is overruled, the daemon logs a warning naming the field, so a mount you asked not to have is never silently there.

A bad value is a startup error naming your file rather than a silent fallback — an unparseable cache_ttl stops the daemon instead of quietly reverting to 30s. Once the daemon is running, a later breakage in the file is downgraded to a warning and the overlay is skipped for that reload, so a stray character in your preferences can never stop the daemon picking up rules and enrolments.

The file must not be writable by anyone else

dotvault refuses to read it — and refuses to start — if either the file or its containing directory is group- or world-writable. It turns a secrets mount on and decides where the secrets appear, so a path another account can rewrite is not something to merely warn about. chmod go-w ~/.config/dotvault ~/.config/dotvault/config.yaml if you hit this.

cache_ttl is capped at 10 minutes here and in the system config alike: the cache window is also the window in which a revoked secret stays readable, and a longer one is never worth it for a cache whose job is to absorb the burst of stats a single ls -l produces.

dotvault status names the file when it contributed, so a mount that policy did not ask for can be explained:

$ dotvault status
...
Filesystem:
  mountpoint:  /home/gary/vault
  mode:        read-only
  cache ttl:   30s
  preferences: /home/gary/.config/dotvault/config.yaml
  state:       mounted

The file must be a single YAML document — a --- separator is refused rather than having everything after it silently ignored.

Requirements

Platform Requirement
Linux A FUSE-capable kernel (/dev/fuse) and the fusermount3 helper, from the fuse3 package on most distributions. The helper is privileged (setuid root, or file capabilities on distros that prefer them), so a service manager that sets NoNewPrivileges= will break the mount — see Troubleshooting. A daemon with CAP_SYS_ADMIN can mount without the helper
macOS macFUSE, installed separately. macOS requires approving its kernel extension in System Settings
FreeBSD The in-kernel fusefs module
Windows Not supported. Setting fuse.enabled logs a warning and mounts nothing

Windows has no FUSE. The nearest equivalent, WinFsp, is a DLL reached through cgo, and dotvault ships CGO_ENABLED=0 static binaries — so rather than carry a dependency it cannot build, the daemon treats the setting as inert there. A config shared across a mixed-platform fleet is safe: the Windows hosts ignore the section and start normally.

Mounting is never fatal. If FUSE is unavailable the daemon logs the reason once and carries on syncing, serving its API socket and running its SSH agent. The failure is not retried — the causes (no /dev/fuse, no helper binary, macFUSE not installed, mountpoint occupied) do not clear on their own, and a retry loop would just log forever.

What you see

The mount root is your own KV prefix, {kv_mount}/{user_prefix}{username}/, so a secret at kv/users/gary/gh is ~/.dotvault/gh.json. It is not possible to reach another user's secrets through the mount: the prefix is bound at construction, not derived from the path you ask for.

Grouped keys nest the way you would expect. An enrolment key of databricks/prod lives at ~/.dotvault/databricks/prod.json, with databricks as a directory.

Exactly one extension is added, so the mapping is reversible: a secret genuinely named config.json in Vault appears as config.json.json. That looks odd, and it is the honest spelling — anything cleverer would make two different secrets share one filename.

stat reports:

  • size — the exact byte length of the rendered JSON, so wc -c, mmap and anything else that trusts st_size get the truth.
  • mtime — the current version's created_time from Vault. This is KVv2's nearest equivalent of a modification time, and it means make-style staleness checks and ls -lt do something meaningful.
  • mode — 0400 for files and 0500 for directories on a read-only mount, 0600/0700 when read_write is on, so test -w agrees with what a write would actually do.

The mount is owner-only. dotvault deliberately does not offer FUSE's allow_other: the whole premise of a per-user daemon is that the secrets it holds belong to one uid.

Reads reach Vault

A file in this mount is not a copy on disk — a read that misses the cache calls Vault. That is what keeps it live, and it is why grep -r across the mount is a bad idea: it will read every secret you have, and each read shows up in Vault's audit log. Reach for a specific path. The same goes for an editor or IDE that indexes your home directory in the background.

Caching

cache_ttl (default 30s) is how long a directory listing or a rendered secret is reused before Vault is asked again.

This is not really an optimisation. A filesystem asks far more questions than a person does: a single ls -l stats every entry, and stat needs the file's size, which can only be known by rendering the document. Without a cache, one ls -l is one Vault read per secret, every time. Lookups that find nothing are cached too — a miss is the most common request a mounted filesystem gets, from shell completion and from every tool probing for a config file it might have.

Set cache_ttl: "0" to disable caching entirely and pay a Vault round trip per operation. Writes through the mount invalidate their own entries immediately, so a read straight after a write always sees what was just written; the only staleness you can observe is a secret changed by something else within the window.

Read-write mode

read_write: true allows writes. It is off by default even though the daemon's token can usually write, because the token's write capability exists for dotvault's own sync and enrolment work — exposing it through a filesystem puts every process running as you, and every mistyped shell redirect, one > away from replacing a credential. Opting in is a separate decision from mounting.

With it on:

# Replace a secret: the whole document is written as one new KVv2 version
$ jq '.oauth_token = "gho_new"' ~/.dotvault/gh.json > /tmp/gh.json && cat /tmp/gh.json > ~/.dotvault/gh.json

# Create one
$ echo '{"token":"abc123"}' > ~/.dotvault/scratch.json

# Create one under a new group
$ mkdir ~/.dotvault/databricks
$ echo '{"host":"https://x.cloud.databricks.com"}' > ~/.dotvault/databricks/prod.json

# Delete one — every version of it
$ rm ~/.dotvault/scratch.json

Edit through a scratch file, not in place

In-place editors and sponge write a temp file beside the target and rename it over. Rename is refused here, so the temp file is created as a real secret in Vault, written, and then unlinked — which deletes every version of it. It works, but it churns your KV store with a short-lived secret each time. Stage the edit outside the mount, as above.

The rules:

  • A file's contents must be a JSON object with at least one field. The write is applied on close(), so invalid JSON surfaces as a failing close (EINVAL) rather than as a silently discarded edit. Numbers survive the round trip exactly — reading and rewriting a secret unchanged does not turn 1000000 into 1e+06.
  • A write replaces the whole document. There is no field-level merge; the file is the secret's data section, and writing it creates one new KVv2 version.
  • rm deletes every version, not just the latest. There is no filesystem gesture that means "soft delete", so unlink is the destructive one.
  • mkdir creates a directory that exists only in memory until a secret is written inside it. KVv2 has no directories of its own — a folder exists because secrets exist beneath it — so there is nothing for mkdir to write. An empty one disappears at unmount. rmdir removes it while it is still empty; on a directory backed by real secrets it reports ENOTEMPTY, because emptying it is what removes it.
  • rename is not supported — mv reports "Operation not supported" (ENOTSUP). Renaming a secret means read, write elsewhere, delete: three Vault operations that cannot be made atomic, where a partial failure leaves you with two copies or none.
  • A new file must be named .json, and a new directory must not be. echo ... > ~/.dotvault/thing is refused (EINVAL): the file would appear as thing.json on the next listing, renaming itself the moment you looked away. mkdir ~/.dotvault/thing.json is refused for the mirror reason — it would shadow the secret thing, which is the one filename collision the extension does not otherwise remove.
  • Appending is refused (EINVAL at open). Appending to a JSON document does not produce a JSON document, and failing at open is more useful than failing at close.
  • touch on a new name fails. A secret with no fields is not something KVv2 stores, so creating a file commits you to writing something valid to it. Use echo '{...}' > file.
  • Files are capped at 1 MiB. A KV secret holding a megabyte of JSON is a misuse of the mount; the cap mostly exists so a runaway redirect cannot grow the daemon's memory without bound.

Layout

A secret and a folder may share a name. users/you/databricks and users/you/databricks/prod both exist happily: the first is ~/.dotvault/databricks.json, the second is ~/.dotvault/databricks/prod.json. Two different filenames, both reachable — which is the second thing the extension buys, after the syntax highlighting.

One collision survives, and it is narrow: a KV folder whose name already ends in .json competes with the secret of the same stem. A folder report.json/ and a secret report both want the filename report.json. The behaviour is deterministic — the directory wins, so the secrets underneath stay reachable — and the daemon logs a warning naming the path, but the shadowed secret has no path in the mount. Read it through the web UI or vault kv get. The mount refuses to create such a directory, so it can only arise from a KV tree laid out that way already.

Client certificates

With client_cert.enabled, three more files appear at the root of the mount, for tools that speak mutual TLS and want to present a certificate for you:

$ ls ~/.dotvault
client.crt  client.key  client.pem  databricks  gh.json  jfrog.json

$ curl --cert ~/.dotvault/client.pem https://service.example.com/
File Contents
client.pem The certificate chain followed by the private key, in one file. Prefer this one.
client.crt The leaf certificate followed by its CA chain (PEM)
client.key The private key (PKCS#8 PEM)

Use client.pem wherever the tool accepts it (curl --cert client.pem). The certificate is replaced every few minutes, and client.crt and client.key are two files: a rotation that lands between a tool reading one and the other pairs a certificate with the wrong key, and the handshake fails. client.pem is one read, so it can never be mismatched. Keep the two-file form for tools that need it (curl --cert client.crt --key client.key), and for those read both files for every new connection rather than caching them.

All three are produced from a single certificate and key, so any one read is self-consistent. The certificate is short-lived by default (five minutes) and is replaced before it expires without anything for you to do; whether it is a freshly signed certificate or the one the daemon itself logs in to Vault with depends on your auth method, and is described in the config reference.

How the files behave differs from the secrets beside them, because their contents change every few minutes and depend on the daemon's token rather than on one KV version:

  • They are read-only even on a read_write mount, mode 0400. Writing, removing or renaming one is refused.
  • Reads always come straight from the certificate source, not from the mount's cache: they are served with direct I/O and a kernel attribute timeout of about a nanosecond, so a tool never sees a superseded certificate for up to cache_ttl longer. stat reports the certificate's NotBefore as the mtime and the exact size.
  • A read or an ls -l of the mount root can trigger a signing (a Vault call) when the cached certificate is due for replacement, because stat needs a size and the size needs the file. At most one signing runs at a time and concurrent readers share it; a failed signing is retried no sooner than 10 seconds later, doubling to five minutes, so a policy that denies it does not turn a polling tool into a stream of denied requests. Between signings a read always returns the still-valid certificate if there is one. When there is none, what it gets depends on why no signing is running. After a failed signing, while the retry is backing off, the read gets that signing's failure again: an I/O error (EIO) for a denial or any other Vault error, and the daemon log names the cause — the PKI mount, the role and Vault's answer — once when it first appears and then at most every ten minutes while it persists, so a polling tool does not flood the log. When nothing has failed and the next signing is simply not due yet (signings with the same token are at least 10 seconds apart), or the daemon holds no Vault token yet, or its token is being replaced and the replacement has not finished within 30 seconds, the read gets EAGAIN: try again shortly. A read also gets EAGAIN when its own 30-second budget runs out while a signing is still in progress — the signing is not abandoned, so the retry gets its result; only a signing that itself failed or timed out against Vault is reported as EIO.
  • A KV folder named client.crt, client.key or client.pem at the root is hidden behind the certificate, and the daemon logs a warning naming it. The certificate wins, matching how the mount resolves its other collisions. Secrets cannot collide, since every secret filename ends in .json.

Under plain mtls the key is your Vault login

If you authenticate with auth_method: mtls, the files hold the certificate the daemon logs in to Vault with. Anything that can read client.key can log in to Vault as you until the certificate expires. The mount is owner-only, but every process you run can read it. See the security notes. Plain mtls has no way to keep the two apart: the held certificate is always served when one is enrolled, and client_cert.pki_role is only the fallback for when it is not. If that is not acceptable, use mtls+tpm, mtls+os or a non-certificate method, which serve a separately signed short-lived certificate instead.

If the certificate files do not appear, client_cert.enabled is off or the section could not be built; the daemon logs the reason once at startup. dotvault status shows which source would be used and GET /api/v1/status shows what is being served.

Permissions

The mount only shows what your Vault token can read, so a token scoped more tightly than your KV prefix simply sees less.

A policy that grants read on specific paths without granting list on their parent is handled: ls reports the permission error, but opening a path you know the name of still works, because the lookup falls back to reading the path directly.

Troubleshooting

The mount fails under systemd, with a fusermount permission error (Linux) — the daemon reports something like fusermount exited with code 1, and the helper's own message on stderr is typically mount failed: Operation not permitted. The service unit is setting NoNewPrivileges=, directly or by implication. It makes execve ignore the setuid bit and file capabilities for the daemon and every process below it, and the mount helper is privileged exactly that way; dotvault asks the kernel to mount directly first, but that needs CAP_SYS_ADMIN, which a user manager cannot grant, so the helper is the only path left.

Removing just that one line is usually not enough. RestrictNamespaces=, RestrictSUIDSGID=, LockPersonality= and the other seccomp-based directives (RestrictRealtime=, MemoryDenyWriteExecute=, SystemCallFilter=, ProtectClock=, ProtectKernelTunables=, PrivateDevices= …) each make systemd imply NoNewPrivileges=yes in any unit that cannot install the filter otherwise — which is every user-manager service — so the whole class has to come out together. The exception is a directive your systemd is too old to know (RestrictSUIDSGID= needs 242+, LockPersonality= 235+) or a build without seccomp support: those are ignored, and imply nothing. Do not rely on that, since it varies by distro.

The packaged dotvault.service ships without them and explains why in a comment. If you run a hand-rolled unit, or a systemctl --user edit drop-in, check it against that one — see Deployment.

Transport endpoint is not connected — a daemon died without unmounting. The next daemon start detects this and clears it automatically. To clear it by hand: fusermount3 -u ~/.dotvault (Linux, or fusermount -u on older fuse2 systems) or umount ~/.dotvault (macOS).

The daemon will not exit — something is holding the mount busy, most often a shell whose working directory is inside it. dotvault retries the unmount for about three seconds, then leaves the mount in place and logs which mountpoint it could not release, rather than refusing to shut down. cd out and unmount by hand.

ls hangs, then everything reports ETIMEDOUT — Vault is unreachable. Each operation is bounded at 30 seconds; a filesystem call that never returns would leave the calling process in uninterruptible sleep.

Reads fail with Permission denied — Vault rejected the request (an expired token, or a policy that does not cover the path). Check dotvault status.

See also

  • Config File Reference — the full field table and the Windows GPO equivalents
  • Sync Rules — writing specific fields into specific files, which is what you want for a tool that reads a fixed config path
  • SSH Agent — the other live surface over the daemon's Vault token