OpenVireo is a password manager built on KeePass files. Every vault is a .kdbx file encrypted with a key that only the user’s devices have. To keep those files in sync across a laptop, a phone and a browser, something has to sit in the middle, and that something should never be able to read them.
That one constraint decides almost everything about the sync server: what it stores, what it checks, who merges, and how it scales. This post walks through the design, from the HTTP contract to running several instances behind a load balancer, and ends with what a load test showed and what the design costs.
The server is open source (openvireo-sync-server, C++ on Drogon), and anyone can run it themselves.
The constraint
The server gets an encrypted blob and an access token. It can’t decrypt the blob, so it can’t:
- look at entries, or tell which one changed,
- merge two versions,
- validate the contents beyond the file format’s header,
- index anything for search.
What it can do is store bytes, compare hashes, and keep order. So the design splits the work: the server decides which version is current, and the clients do every bit of merging. The server stays small (about 5,500 lines of C++, both storage backends included), and a compromised server leaks ciphertext and metadata, not passwords.
Sign-in has the same goal. Accounts use OPAQUE, so the account server never sees the password either.
The server compares, the client merges
Each database has an ETag: the SHA-256 of the file. Every upload has to say which version it replaces:
If-None-Match: *creates the database, and fails with412if it already exists.If-Match: "<etag>"replaces exactly that version, and fails with412if another device got there first.- An upload with neither header gets
428 Precondition Requiredwhen the database already exists.
A sync is then a short loop on the client:
GET /api/v1/databases/personal → 200, ETag: "a1f3…", the encrypted file (decrypt, merge with the local copy, save locally, re-encrypt)PUT /api/v1/databases/personal If-Match: "a1f3…" → 200, new ETag "7c0e…" or 412: someone uploaded first, go back to GETOn 412 the client downloads the new version, merges again and retries, up to five times. Two devices can’t silently overwrite each other: one wins, the other notices and merges. This is optimistic concurrency, the same idea as a compare-and-swap. It works here because the server never has to understand what it’s comparing.
Polling is cheap too. A GET with If-None-Match: "<etag>" gets 304 with no body when nothing changed. In the load test below, most downloads were 304s.
Three-way merge on the client
Merging two KeePass files by “newest file wins” loses data the moment two devices edit offline. So the clients do a three-way merge against the base copy, the last version both sides had:
- For each entry edited on both sides, merge field by field against the base. A field only one side changed takes that side’s value. A field both sides changed takes the newer value and is reported as a conflict.
- Then merge the structure: entries and groups added, moved or deleted, using UUIDs to match items and modification times to order changes.
The base is why the client keeps a copy of what it last synced, along with the ETag and revision. Without it you can’t tell “I deleted this” from “you added this”.
The hard part isn’t the algorithm, it’s agreement. The desktop app (C++/Qt), the web app and SDK (TypeScript) and the iPhone app all sync the same files, so they all have to produce the same merge result. That’s now handled by a shared Rust core that every client calls, checked against fixtures recorded from the original Qt client. When two implementations disagree, a test fails, instead of a vault quietly diverging.
What the server does check
Not reading the contents doesn’t mean accepting anything:
- The file signature. An upload has to start with the KDBX magic bytes, or it gets
415. That catches clients uploading the wrong thing, not attackers, and the server doesn’t parse anything past it. - Size. Uploads over the limit (50 MiB by default) get
413before the body is read. - History. Before each overwrite, the previous version is kept, ten by default. Restoring an old version doesn’t change anything on the server: the client downloads it and uploads it again as a new version. A bad merge is never more than one restore away.
- Per-device tokens. On a self-hosted server each device has its own token, so a lost phone can be revoked without signing everything else out.
Telling the other devices
Polling every few seconds would make sync feel instant and waste nearly every request. Instead, clients keep a server-sent events stream open:
GET /api/v1/events
retry: 5000
event: databasedata: {"id":"personal","etag":"\"7c0e…\"","revision":12}
: pingWhen another device uploads, the server pushes the new ETag and the client syncs straight away. A comment line every 25 seconds keeps idle connections alive through proxies and NAT. With the stream connected, the desktop app only polls every five minutes as a safety net.
SSE over WebSockets was an easy choice: the traffic only goes one way, it’s plain HTTP (so the same auth header and CORS rules apply), and browsers reconnect on their own.
The part that takes debugging is everything between the server and the client. Reverse proxies love to buffer responses, which holds events until the buffer fills. The server sends X-Accel-Buffering: no, and the docs ask for this in nginx:
proxy_buffering off;proxy_read_timeout 1h;From one disk to several instances
The first version kept everything on local disk: files, metadata, and an in-process mutex per database, held around the If-Match check and the write. That’s correct for one process. With two instances behind a load balancer, both can pass the check and both commit.
The hosted version runs stateless containers on Postgres plus an S3-compatible bucket. Postgres decides every commit, and the bucket only holds bytes under keys that are never overwritten:
- Write the new blob to a fresh key in the bucket.
- In one transaction:
SELECT … FROM databases WHERE user_name = $1 AND id = $2 FOR UPDATE. The row lock replaces the mutex, and it works across instances.- Check
If-Matchagainst the row, and roll back with412if it doesn’t hold. - Copy the current row into
versions, then write the new revision, ETag and blob key. - Trim
versionsto the history size. NOTIFY sync_eventswith the event.
- After the commit, delete blobs that nothing references any more.
A few things fall out of this:
- The bucket needs nothing special. Only plain PUT, GET, DELETE and LIST, so it doesn’t depend on S3 conditional writes, which not every S3-compatible store supports.
- Losing writers leave orphans. A writer that gets
412, or crashes after step 1, leaves an unreferenced blob. A sweep deletes unreferenced blobs older than an hour, on whichever instance holds an advisory lock. - Events cross instances for free. Each instance holds one
LISTENconnection and forwards notifications to its open streams. Postgres only delivers aNOTIFYif the transaction commits, so a device never hears about an upload that rolled back.
LISTEN/NOTIFY has a ceiling: a notifying commit holds a database-wide lock while it flushes. At a rough 1–5 ms per commit, that’s 200–1,000 uploads a second. Assuming each active user’s devices upload about three times an hour, that’s far beyond what the service needs for a long time, and when it isn’t, the notifications can move after the commit or to a real queue.
Self-hosted installs keep the filesystem backend: one binary, a SQLite file for users and devices, and a folder of .kdbx files per user. Nothing else to run. Both backends sit behind the same two interfaces, so the HTTP API and the clients don’t know which one they’re talking to.
What a load test showed
I load-tested the full stack with k6. Each iteration is one client sync check: list vaults on the account and sync servers, a conditional download (mostly 304), a 200 KB upload one time in five, and a token refresh when the access token gets old. Every virtual user comes from its own IP so rate limits apply, and each container is capped to a small slice of CPU: the auth server at half a core, the sync server at 0.15.
| Ramp to 120 syncs/s | Ramp to 600 syncs/s | |
|---|---|---|
| Requests | 37,934, 0 errors | 91,647, 0 errors |
| Auth p95 | 12 ms | 1.2 s (saturated) |
| Sync p95 | 1.2 ms | 1.2 ms |
| Sync CPU / RAM | 6% / 33 MB | 11% / 103 MB |
The sync server holds 1.2 ms at p95 throughout, on 0.15 of a core. That’s the payoff of a server that only compares hashes and moves bytes: there’s almost nothing to compute. The bottleneck is the Python account server, mostly token refreshes, and for storage, disk space for version history runs out long before CPU does.
What it costs
- No sharing on a self-hosted server. Sharing a vault means encrypting its key to several people and managing who has access. The hosted service does that with an account server, organizations and per-vault keys. A self-hosted server just syncs each user’s own files.
- No server-side features. No server-side search or reports, and no server-side merge to fix a broken client. Anything that needs the plaintext runs on a device.
- Every client has to merge identically. That’s what the shared core and the recorded fixtures are for, and it’s still the part of the system that needs the most tests.
- Whole-file uploads. Changing one entry re-uploads the whole encrypted file. KeePass files are small, so this costs little, and in exchange every device has a complete file that any KeePass app can open, with or without the server.
For a password manager, those are the right trade-offs. The server knows when your vault changed and how big it is, and that’s all.
If you want to run it yourself, the self-hosting guide covers setup in a few minutes, and the sync server docs have the full API. There’s more on the rest of the system on the OpenVireo project page.