Design · Architecture
How veilpass fits together
Three pieces: an encrypted file, an app that opens it, and an optional peer-to-peer network that lets your other devices open it too. No accounts, no servers holding your data.
The vault: a single encrypted file
Everything you put in veilpass — passwords, notes, one-time-code
secrets, tags — lives inside one file with the .veilpass
extension. That file is encrypted end-to-end from the moment it's
written. If you copy it onto a USB stick and hand it to a
stranger, they have a locked box; the passphrase is the only key.
The same file format works on every platform. Move it between devices manually if you like — sync is optional.
The app: native on every platform, same file underneath
There are three surfaces you'll see:
- Mobile app (Android + iOS) — full read/write, OS-level autofill, biometric unlock, TOTP scanner, device pairing.
- Desktop app (macOS, Linux, Windows) — same feature set as mobile plus a native file picker for the vault.
- Browser extension (Chromium-family) — inline autofill and save-on-submit on web pages, popup for browsing entries.
All three read and write the same .veilpass file
format. The heavy lifting (encryption, key derivation, sync)
runs in a shared Rust core so every platform gets the same
audited behavior.
The network: opt-in, peer-to-peer, no accounts
Sync is turned off by default. Turn it on and your device joins Veilid, an open peer-to-peer network. Your vault ciphertext (the same bytes that live on disk) is published to a distributed hash table under a record key. Any device that holds that record key and the passphrase can pull the vault down. There is no server we operate. There is no account to phish.
Getting a second device joined is a matter of reading it seven words from the first device. The seven words are a pairing token — a compact secret that lets the second device derive the record key and everything else it needs.
What each piece is for
| Piece | What it holds | Trust boundary |
|---|---|---|
| Passphrase | The one secret you must remember. | Your head. |
| Vault file | All your entries, encrypted with a key derived from your passphrase. | Whatever storage you keep it on. |
| App | Opens the file, shows entries, writes changes. | Your device. |
| Veilid DHT (optional) | The same encrypted bytes, so a second device can fetch them. | The public Veilid network. |
What isn't here
No accounts. No email/password login. No "sign in with Google". No support portal that can reset your passphrase. No server that stores your vault plaintext. No plaintext cloud backup.
If you forget your passphrase, the vault is unrecoverable. The reason there's no "forgot password" is the reason no one else can read your vault either.
Read more
- Cryptography — key hierarchy, algorithms, and what happens when you change your passphrase.
- Peer-to-peer sync — how devices find each other on Veilid, what pairing tokens actually are, and what leaks on the wire.
- Threat model — what we defend against, what we explicitly don't defend, and what to do if a device is lost.