Skip to content

Run programs with secrets

Instead of putting a secret in a file, put a vault:// reference there and let vaultfold fill it in for one process.

  • A vault with at least one entry (see store and read).
  • An existing env file or template to hold the references. link edits files in place; it does not create them.

Write a reference into an env file, then run the command. Every variable whose whole value is a reference is replaced in the child's environment only. Env files are read, never written.

Terminal window
touch .env
vaultfold link .env DB_PASS vault://app/db#password
vaultfold run --env-file .env -- npm start

Everything after -- is the command and its arguments. All references are resolved before the command starts; if one cannot be resolved, nothing runs. When output goes to a terminal, resolved values of 8 bytes or more are replaced by ***. Use --mask-min to change the threshold.

Environment variables are visible to the child and, through the process table, to other processes with the same privileges. For the most sensitive values, deliver the value on a file descriptor instead (not on Windows).

Terminal window
vaultfold run --fd 4=vault://app/db#password -- sh -c 'cat <&4'

inject replaces references in a template and writes the result to standard output, resolving everything before anything is written.

Terminal window
printf 'host=db.internal\npass=vault://app/db#password\n' > app.conf.tmpl
vaultfold inject -i app.conf.tmpl

To give a program a real file, render to a temporary file that is zeroed and removed when the command exits. This asks you to type write on a terminal and never overwrites an existing file.

Terminal window
vaultfold inject -i app.conf.tmpl --to-file app.conf --ephemeral -- ./start-server

If a run is interrupted, vaultfold inject --wipe removes any leftover files.

  • Vault commands start the agent daemon and unlock once; run and inject have the daemon resolve references so no key reaches them. Set VAULTFOLD_NO_AGENT=1 to skip the daemon and unlock in-process for that command only.
  • Encoded forms of a value (base64, URL encoding) are not masked, and a masked child sees pipes rather than a terminal.
  • A script that runs many vault commands back to back can hit the daemon's rate limit (60 requests a minute, burst of 20); batch references into one run.
  • --to-file needs a terminal to confirm, and on Windows run --fd is refused.