Post-quantum file encryptionvault.

02Why it's different

Three things most encryption tools don't do

What vault is not

• Not a sync service. It's a folder. Sync the folder yourself if you like; vault doesn't.
• Not a backup by itself. One copy of anything is zero copies. Back up the vault folder and your key.
• Not magic against malware. If something is watching your keyboard as you type the passphrase, no file encryption tool can help.
• Not recoverable without the passphrase. No reset link, no back door. That's the point, and it cuts both ways.

Got two minutes? Here's all of it

1. vault genkeyMake your key. Pick a good passphrase.
2. vault initMake your vault.
3. vault add taxes.pdfPut something in.
4. vault lsSee what's in there.
5. vault get taxes.pdfGet it back out.

That's the tool. The rest of this page is detail, safety rails and the decoy trick.

03Install

Download, check, run

vault is a single self-contained program: no installer, no runtime, no dependencies. Pick the file for your system (yours is highlighted if your browser says what it is), check it, rename it to vault (or vault.exe) and put it on your PATH.

Not sure which Linux you have? Run uname -m: x86_64 is amd64, aarch64 is arm64, armv7l is armv7 and armv6l is armv6.

Check the file hasn't been tampered with

Every release has a SHA256SUMS file. Checking takes ten seconds, and for an encryption tool it's the difference between running vault and running something pretending to be vault.

# Linux
sha256sum -c SHA256SUMS --ignore-missing

# macOS
shasum -a 256 -c SHA256SUMS --ignore-missing

# Windows (PowerShell): compare with the line in SHA256SUMS
Get-FileHash .\vault-windows-amd64.exe -Algorithm SHA256

You want to see OK. Anything else: stop, and download it again.

Put it on your PATH

Linux and macOS, from the folder you downloaded into:

sha256sum -c SHA256SUMS --ignore-missing
chmod +x vault-linux-amd64
sudo mv vault-linux-amd64 /usr/local/bin/vault
vault help

No admin rights? Use ~/.local/bin, which most distributions already have on the PATH.

Windows: make a folder such as C:\Tools, move the file in renamed to vault.exe, search the Start menu for "environment variables", open Edit the environment variables for your account, add C:\Tools to Path, and open a new terminal.

Android (Termux), after downloading with your phone's browser and running termux-setup-storage once:

cp ~/storage/downloads/vault-android-arm64 .
chmod +x vault-android-arm64 && mv vault-android-arm64 $PREFIX/bin/vault

Manual pages

There's a manual page for vault and one for every command. Download vault-man-pages.tar.gz, then:

mkdir -p ~/.local/share/man/man1
tar -xzf vault-man-pages.tar.gz -C ~/.local/share/man/man1
man vault-absorb

Did it work?

Run vault help and you should see every command on one screen:

Building it yourself

With Go 1.26.6 or newer, go build . makes a binary for your platform, and ./build.sh cross-compiles all 43 targets into ./dist with a SHA256SUMS. Set TARGETS for a subset and OUT for a different folder. The builds are static and reproducible: no C code, paths stripped, build IDs zeroed, so two people building the same commit get byte-identical files.

04Your key

The one file that matters most

vault genkey creates your key at ~/.vault/key, protected by a passphrase. It asks twice, and nothing appears as you type. That's deliberate, not broken.

Choosing a passphrase that doesn't suck

The key is sealed with your passphrase through Argon2id, a deliberately slow, memory-hungry function: every guess costs an attacker real time and 64 MiB of memory. That only helps if there are a lot of guesses to make.

• Use four or more random words. correct horse battery staple beats P@ssw0rd! by a mile, and you can remember it.
• Make it unique. Not your email password, not your bank's.
• Make the decoy believable. Something you would genuinely pick.

Where it lives

By default the key is ~/.vault/key (%USERPROFILE%\.vault\key on Windows). Put it somewhere else, such as a USB stick, with --key or VAULT_KEY:

vault genkey --key /media/usb/vault.key     # this once
export VAULT_KEY=/media/usb/vault.key       # every command from now on

Keeping the key on a stick and the vault on your laptop is a neat trick: pull the stick out and the vault is inert, even to someone who knows the passphrase. Two things to steal instead of one.

Back. It. Up.

The key file is encrypted, so a copy is safe somewhere a little less private than your laptop: a USB stick in a drawer (or two, in two drawers), an attachment in your password manager, or printed out. Inside are two equal-sized encrypted slots in random order, and each passphrase opens exactly one. With no decoy, the spare slot is random bytes that look exactly like an encrypted slot, so the file says nothing about whether a decoy exists.

05Your first vault

One command, and a peek inside

vault init creates an empty vault at ~/.vault/store. No passphrase needed: an empty vault has nothing to protect yet.

Inside records/ and objects/ are 256 folders each, named 00 to ff. Every encrypted file lives in the one matching the first two characters of its name, which keeps any one folder from getting huge. All 256 exist from the start, so the layout itself gives nothing away.

Wait, why is there already stuff in it?

A new vault holds between 8 and 32 entries of random filler, encrypted to a key that was thrown away the moment it was used. Nobody can open them: not you, not anyone. It's what makes the decoy believable. Every vault, decoy or not, always contains entries you can't open, so someone holding your decoy passphrase finds nothing remarkable about entries they can't read.

More filler, for bigger secrets

vault init --filler 2G

The default few tens of megabytes of filler can only cover for a few files. Sizes take K, M, G or T. The filler is shaped like a real collection, small and large "files" mixed, so a big file of yours sits among big files of filler. It can only be chosen at init: added later, it would show up as a burst of new entries, which is exactly what it's meant to hide.

More than one vault

vault init --vault ~/work-vault
vault add contract.pdf --vault ~/work-vault

Or set VAULT_DIR in your shell profile and never type --vault again. One key works with any number of vaults.

06Everyday moves

add, list, get, mv, rm

The five commands you'll actually use. Each asks for your passphrase.

Putting things in: add

vault add FILE-OR-FOLDER-OR-URL [FOLDER-IN-VAULT]

• Documents/tax-return-2025.pdf became plain tax-return-2025.pdf: vault keeps the file name, not the path you typed.
• With a second argument, the passport scan landed in id/passport-scan.jpg.
• Adding the folder Documents/letters kept its name and structure: letters/bank.txt, letters/landlord.txt.
• Adding . brings in a folder's contents, subfolders and all, without a folder name of its own.

Folders inside a vault aren't real folders, just part of each file's name, so there's no mkdir and a folder disappears with its last file. Adding a name that already exists replaces it, and the old version is deleted only after the new one is safely stored, so a crash never leaves you with neither. Anything that isn't a plain file (symbolic links, sockets, devices) is skipped with a note, and so are the vault and key themselves if they live inside the folder. Files over 1 TiB are refused.

Seeing what's inside: ls and list

vault ls              # the top level: folders (ending in /) and files
vault ls letters      # one level down, inside letters/
vault list            # every file, all the way down, full names

ls works like the shell's: one folder at a time. Each sub-folder appears once, ending in /, with the total size of everything inside it and its newest date; files show their own size and date. Folders come first, then files, and vault ls letters/2025 keeps going down. list is the whole catalogue in one go, with full names: the one to pipe into other commands. vault ls -r does the same.

Each line is the size, the file's own modification time and its name, sorted. list needs your passphrase because the names are encrypted too: without the key, vault can't read the catalogue any better than a thief can.

Getting things out: get

vault get NAME               # writes the file here, under its own name
vault get NAME -o OUTPUT     # writes it wherever you say

• It never overwrites. If the output exists, vault stops. Move the old one or use -o.
• Nothing appears until everything checks out. vault writes to a hidden temporary file, verifies every byte, and only then gives it its real name. A tampered or damaged file never shows up half-written.
• It restores the details: the original permissions and modification time.

Renaming and deleting: mv and rm

vault mv notes.md ideas/notes.md    # NEW is the full new name, folder included
vault rm letters/bank.txt           # one file, immediately
vault rm -r old                     # a folder and everything in it; asks first
vault rm -rf old                    # the same, without asking

mv won't overwrite an existing name and doesn't re-encrypt anything, so it's instant at any size. rm removes the catalogue entry and every encrypted piece of the file, so the space comes back straight away.

Deleting a whole folder: rm -r

rm -r deletes a folder and everything under it. Because that can be a lot, it first lists what's going (the first 20 names, then a count) with the total size, and asks. Anything but y deletes nothing, and so does having no terminal to ask on. -f skips the question and also means "don't complain if there's nothing there", so rm -rf is the one for scripts. vault rm -r / is refused rather than emptying the vault.

Flags work anywhere

--key PATH and --vault DIR work with every command, before, between or after the arguments:

vault add --vault ~/work report.pdf
vault add report.pdf --vault ~/work
vault add report.pdf --vault=~/work

07More ways in

URLs, whole websites and tar streams

Straight from the web

Give add an http:// or https:// address and vault downloads it (with a Chrome user agent, so fussy sites play along) and stores it under the last part of the address. The download sits in a private temporary file only until it's encrypted.

vault add https://example.com/reports/annual.pdf work    # stored as work/annual.pdf

Copying a website: mirror

mirror crawls a whole site, one request at a time and only on the same host, into a folder named after the host. Links in HTML (href, src, action, poster) and CSS (url(…)) that point into the copy are rewritten to relative paths, so it still browses once you get it back out.

Pages that fail are reported and skipped; the crawl carries on. Links built by scripts and srcset lists aren't followed, and there's no depth limit or robots.txt handling, so only mirror sites you may copy.

From a tar archive: absorb

absorb reads a tar archive, gzipped or not, from standard input and stores every plain file in it, optionally under a folder, keeping the paths, permissions and dates recorded in the archive:

tar -cz photos | vault absorb backup                  # backup/photos/...
vault absorb backup < photos.tar.gz                   # an archive you already have
ssh server 'tar -C /etc -c .' | vault absorb server1/etc
gpg --decrypt cpt.tar.gpg | vault absorb cryptdrive   # straight out of another tool

Each file is encrypted straight from the stream, so nothing is unpacked to disk first: the way to move a tarball, or another tool's encrypted archive, into vault without plaintext ever touching the drive. Directories need no entry of their own; links, devices and any name that tries to climb out with .. are skipped with a note. If the archive stops halfway through a file, that file isn't stored and vault stops with an error; everything before it is already safely in.

Moving in: migrate

migrate works exactly like add but deletes each original once it's safely stored, then tidies away any folders left empty. It won't take a URL: there's no original to delete. Because the originals go, it checks first: if anything would replace a file already in the vault, it lists those names and asks before touching anything. Anything but y changes nothing, no terminal means no, and --yes answers yes up front for scripts.

Setting up a decoy

1. Run vault genkey and type your real passphrase, twice.
2. At Enter decoy passphrase (empty for none), type the decoy, twice. The two must differ.
3. Run vault init --filler 5G, with at least as much filler as you plan to hide.
4. Add some decoy files, typing the decoy passphrase.
5. Add your real files, typing the real passphrase.

In scripts, set VAULT_DECOY_PASSPHRASE alongside VAULT_PASSPHRASE before genkey. Already have a key without a decoy? Make a new key with a different --key, make a new vault, get everything out of the old one and add it to the new. The key format deliberately can't say whether a decoy slot is in use, so there's nothing to upgrade.

Why it holds up

• The key file can't tell. Two slots of identical size in random order. With no decoy one is random noise, indistinguishable from an encrypted slot. Both are tried every time, so even the timing matches.
• The vault can't tell. Real and decoy entries are sealed to different keys but are the same size and shape, all dated 1970. Nothing on disk says which key an entry belongs to.
• The filler covers for you. Every vault has entries nobody can open, so "some entries I can't open" is true of every vault.
• The errors are identical. A real file asked for with the decoy passphrase gets exactly the same "not in the vault" as a typo.

Making it believable

• Fill it with plausibly private things: bank letters, payslips, notes, scans. What someone would encrypt. Two files called test.txt is a neon sign.
• Keep it at least as big as your real collection.
• Keep it alive. Add to it now and then, so the dates look like a real person uses it.
• Know it cold. Hesitating over the "real" passphrase is a tell.
• Never mention it, not in notes, a README, or a script on the same machine.

The honest limits

It won't help if someone saw you type the real passphrase or has malware on your machine. It hides; it doesn't stop anyone deleting the raw files. And it isn't legal advice: some places treat misleading an official as an offence in its own right.

09Scripts and automation

Set the environment, and vault never asks

Exit codes and output

0 means it worked, 1 means something went wrong (the reason is on standard error, starting vault:), and 2 means you ran vault with no command. list and help write to standard output; progress lines like added … and every error go to standard error, so vault list > files.txt gives a clean list. The list columns are fixed-width, which is why cut -c31- works even for names with spaces.

Recipes

Nightly: stash a folder. Re-adding replaces each file, so the vault always holds the latest copy.

#!/bin/sh
# ~/bin/stash-documents: re-adds everything in ~/Documents/private
export VAULT_PASSPHRASE="$(cat ~/.config/vault-pass)"   # chmod 600 this file!
vault add ~/Documents/private archive || exit 1

# crontab: 0 2 * * * $HOME/bin/stash-documents

Back up a server without plaintext touching your disk:

ssh server 'tar -C /srv/app -cz .' | vault absorb "servers/app/$(date +%F)"

Get everything back out, keeping its folders:

#!/bin/sh
vault list | cut -c31- | while IFS= read -r name; do
  mkdir -p "restore/$(dirname "$name")"
  vault get "$name" -o "restore/$name"
done

PowerShell on Windows:

$env:VAULT_DIR = "D:\vault"
vault add .\report.docx
vault list

10Locking, syncing and backups

Two terminals, two machines, and keeping copies

vault locks itself. Commands that change the vault (add, migrate, mirror, absorb, mv, rm) take an exclusive lock; commands that only read (list, get) share one. A command that has to wait says so and carries on by itself. The lock is taken after you've typed your passphrase, so someone slow at typing never blocks you.

If vault crashes holding the lock, the operating system drops it on Linux, macOS, the BSDs and Windows. On Plan 9 and WebAssembly, which have no file locks, vault uses a lock file instead and tells you after a minute exactly which file to delete if one is left behind.

Syncing between machines

A vault is just a folder, so Syncthing, Dropbox, iCloud Drive, OneDrive, rsync or a USB stick will carry it. Copy the key to each machine over something private.

Slips are rarely a disaster: "conflicted copy" files have names vault ignores, and if both machines added the same name, list shows the newest and the next add or rm of it tidies up. NFS honours vault's locks on Linux and the BSDs, and Windows shares honour them from Windows.

Backups

Back up the vault folder and the key file, ideally in different places.

rsync -a --delete ~/.vault/store/ /media/backup/vault-store/
vault list --vault /media/backup/vault-store     # test that the backup opens

11Under the hood

The cryptography, the layout, and what a thief learns

Each file gets its own random 256-bit key, wrapped with a hybrid of FrodoKEM and ML-KEM, and is encrypted in authenticated 64 KiB chunks.

Why two post-quantum algorithms? ML-KEM is the new standard, efficient and heavily analysed. FrodoKEM is slower and bulkier but rests on older, more conservative maths. Combined, a breakthrough against either alone isn't enough.

What's in the folder

~/.vault/store/
├── .vault             marker: "VAULT 2"
├── .lock              lock file, always empty
├── records/0f/
│   └── 0f1170a6…      one encrypted catalogue entry per file, every one 18,704 bytes
└── objects/3e/
    └── 3e78275e…      contents in 4 MiB pieces: 64 KiB, 128 KiB … 4 MiB, never in between

A record holds one file's name, size, permissions, dates and a secret random seed, padded to 4096 bytes before encryption so every record is the same size whatever the name. The contents are cut into objects of just under 4 MiB. Every object starts with its own ID, the last is padded with random bytes up to the next power of two (at least 64 KiB), and each is encrypted separately. Object names are derived from the seed, so only someone who can open the record can tell which objects belong together, or in what order.

Why big files are cut up

As one object, a 300 MB video would be a single 512 MiB blob: obviously one large file, and too big to be filler. Cut up, it's 72 objects exactly the same size as the largest filler and every other big file's pieces, and nothing says which belong together. Small files and last pieces are still bucketed to a power of two, so nothing wastes more than 4 MiB. Totals still show (objects × 4 MiB is a fair estimate of what you store), and someone watching the folder change can see 72 objects appear together. The pieces hide a file's size from a snapshot, not from someone watching you add it.

What an attacker learns

Someone with a copy of your vault folder…

What happens during add

1. Pick a random seed. Read the file 4 MiB at a time, encrypting each piece (the last with random padding) to a hidden temporary file, several at once.
2. Give each piece the name the seed dictates. They're stored, but nothing refers to them yet.
3. Encrypt a record holding the seed into records/.
4. Only then delete any older version of the same name.

Interrupt it anywhere and the worst case is some orphaned encrypted objects that nothing points to. You never get a record pointing at nothing, or lose both versions. vault's crypto core comes from Fury, my larger post-quantum encryption toolkit, which is why every entry's first line still reads fury-encryption.org/v1: changing a well-tested format for looks is how bugs get in.

12When things go sideways

Every message, and what to do about it

Almost every error is a wrong passphrase, the wrong --key or --vault, a typo in a name, or a file already in the way. Your data is still fine.

"My files have vanished!"

Nine times out of ten: you typed the other passphrase (decoy and real are separate worlds), you're looking at a different vault (check --vault and VAULT_DIR), or you're looking in a folder (vault list letters only shows letters/).

Interrupted?

Power cut, closed lid, Ctrl+C: it's fine. vault writes new data first and removes old data last, so the vault stays consistent. At worst there's an orphaned encrypted object or a temporary file starting .pending-, both harmless and safe to delete.

14FAQ

Questions people ask

Every screenshot on this page is real output from the vault binary, run in a throwaway home folder shown as /home/sam. A few lines are highlighted in amber to make them easier to spot.