OpenVireo Sync Server
What the sync server does, how sync works, and a quick start.
A small REST server that stores OpenVireo databases so several devices can stay in sync. It runs on your own machine or server (self-hosted, with a token per device), or as the storage behind OpenVireo accounts (hosted, with access tokens from the account server).
The server only ever sees the encrypted .kdbx file. OpenVireo downloads it, decrypts and merges it
locally, then uploads the merged result. Your master password and keys never leave the client.
The client side lives in OpenVireo (src/gui/remote/), the web app
and the SDK. OpenVireo is a fork of
KeePassXC; this server is not part of or endorsed by the KeePassXC project.
How sync works
Section titled “How sync works”- A device downloads the server’s copy with
GET, together with itsETag(the SHA-256 of the file). - It merges that copy into its local database (the same merge as Merge from Database) and saves locally.
- It uploads the result with
If-Match: "<etag>". If another device uploaded in the meantime, the server answers412and the device starts again at step 1, so two devices can never overwrite each other. - The server keeps the previous versions, and tells every other connected device about the new one over a server-sent events stream, so they sync right away instead of waiting for their next poll.
The server never parses the database beyond checking its file signature. It can’t read entries or merge anything itself.
Quick start
Section titled “Quick start”Download the server for your platform from the releases: one signed binary that needs nothing else installed, for Linux, macOS and Windows. On Linux, for example:
v=VERSION a=x64 # VERSION: the release without the v, e.g. 0.2.0; a: x64 or arm64curl -fLO "https://github.com/OpenVireo/openvireo-sync-server/releases/download/v$v/openvireo-sync-server-$v-linux-$a.tar.gz"tar -xzf "openvireo-sync-server-$v-linux-$a.tar.gz" && cd "openvireo-sync-server-$v"./openvireo-sync-server users add alice laptop # prints laptop's access token, shown only once./openvireo-sync-server # http://127.0.0.1:8787, data in ./dataInstalling and deploying has the macOS and Windows downloads, how to check the signatures, and a systemd unit. There’s also a Docker image.
To build it from source instead (C++17 on Drogon):
brew install drogon sqlite # or: apt install libdrogon-dev libsqlite3-dev, vcpkg install drogon sqlite3, …cmake -S . -B build -DCMAKE_BUILD_TYPE=Releasecmake --build build./build/openvireo-sync-server users add alice laptop./build/openvireo-sync-serverSee From source for Postgres and S3 support, and fully static builds with vcpkg.
Then in OpenVireo:
- Open your database and go to Database → Database Settings → Remote Sync.
- Enter a name, set Type to OpenVireo Sync Server, and fill in:
- Server URL:
http://127.0.0.1:8787, or yourhttps://URL - Database ID: any name, e.g.
personal - Access token: the token printed for this device. It is kept on this device only (in the Keychain on macOS, the Credential Manager on Windows, the desktop keyring on Linux), not in the database
- Server URL:
- Click Test Connection, then Save, then OK.
- Use Database → Remote Sync → <name> to sync.
The first sync uploads your local database. Later syncs download the server copy, merge it with your local database, save it locally, and upload the result. Other devices use the same Database ID; see Users and devices for adding them.
Contents
Section titled “Contents”- Installing and deploying: release binaries, from source, Docker and GHCR images, DigitalOcean, HTTPS
- Configuration: every
SYNC_*variable, and the two storage backends - Users and devices: the command line, pairing, revoking a lost device
- Accounts and vaults: running the server behind an OpenVireo account server
- HTTP API: routes, concurrency, history, events, CORS and errors, with the OpenAPI description
- Operations: backups, upgrades, scaling, monitoring
- Development: building, tests, releases
License
Section titled “License”See LICENSE.