Keep Files in a Post-Quantum Encrypted Vault with vault

vault stores files as encrypted, fixed-size records so a storage host can see neither names, sizes nor contents. This guide walks the whole life of a vault, from key to retrieval, and explains the options every subcommand shares.

Allow about fifteen minutes. You need the vault binary on your PATH and a directory with room for the store. No elevated privileges are needed. Encryption is a hybrid of FrodoKEM-640 and ML-KEM-768 with ChaCha20-Poly1305, and the key file is protected by an Argon2id-derived passphrase key, so the passphrase is the one thing you cannot recover if you lose it.

1. Know the three moving parts

A vault has a key file, a vault directory and a passphrase. The key file defaults to ~/.vault/key and the vault directory to ~/.vault/store. Both can be moved with --key and --vault, or with the environment variables VAULT_KEY and VAULT_DIR. Options may appear before, between or after the arguments, so vault list --vault /srv/v work and vault list work --vault /srv/v are the same command.

2. Create the key and the vault

Two commands set everything up. genkey asks for a passphrase twice, then for an optional decoy passphrase. init builds the empty store and fills it with unreadable filler:

$ vault genkey
$ vault init --filler 500M

Each has its own guide: vault-genkey(1) and vault-init(1). Do both before anything else, because every other command needs the key and the store to exist.

3. Put files in and list them

Add a file, a directory or a URL, optionally into a folder. Then list what is stored:

$ vault add report.pdf work/2026
$ vault add ./photos
$ vault list work

Files added from disk are covered in vault-add(1), or vault-migrate(1) if you want the originals gone afterwards. Whole websites go in with vault-mirror(1). Reading back is vault-list(1) and vault-get(1).

4. Get, rename and delete

Retrieval writes a decrypted copy to a path of your choosing. Renaming and deleting change the vault in place:

$ vault get work/2026/report.pdf -o /tmp/report.pdf
$ vault mv work/2026/report.pdf work/2026/q3-report.pdf
$ vault rm work/2026/q3-report.pdf

5. Skip the passphrase prompt in scripts

Set VAULT_PASSPHRASE and no command will prompt on the terminal. That puts the passphrase in the process environment, so use it only where you trust the account and the machine, and never in a shared shell profile:

$ VAULT_PASSPHRASE='correct horse' vault list

The VAULT_DECOY_PASSPHRASE variable does the same job for the decoy slot during vault genkey.

6. Understand locking

Commands that change the vault hold an exclusive lock on DIR/.lock. Readers such as list and get hold a shared lock, so several can run together but a writer waits for them. The lock is taken after the passphrase prompt, which means a slow typist does not block anyone else. mirror keeps its exclusive lock for the whole crawl, so plan around long runs.

7. Use the decoy passphrase deliberately

If you gave genkey a second passphrase, it unlocks a separate identity. Every command run with it sees and changes only the decoy files, and your real files stay invisible. The key file does not reveal whether a decoy exists, and init fills each vault with unreadable filler, so hidden files look like filler to anyone holding only the decoy passphrase.

8. Read the exit status

Zero means success. One means an error, with the diagnostic on standard error. Two means you ran vault with no command. That is enough for a script to branch on:

$ vault get work/2026/report.pdf -o /tmp/r.pdf || echo "get failed"