Skip to content
OpenVireoDeveloper
GitHub

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.

  1. A device downloads the server’s copy with GET, together with its ETag (the SHA-256 of the file).
  2. It merges that copy into its local database (the same merge as Merge from Database) and saves locally.
  3. It uploads the result with If-Match: "<etag>". If another device uploaded in the meantime, the server answers 412 and the device starts again at step 1, so two devices can never overwrite each other.
  4. 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.

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:

Terminal window
v=VERSION a=x64 # VERSION: the release without the v, e.g. 0.2.0; a: x64 or arm64
curl -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 ./data

Installing 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):

Terminal window
brew install drogon sqlite # or: apt install libdrogon-dev libsqlite3-dev, vcpkg install drogon sqlite3, …
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/openvireo-sync-server users add alice laptop
./build/openvireo-sync-server

See From source for Postgres and S3 support, and fully static builds with vcpkg.

Then in OpenVireo:

  1. Open your database and go to Database → Database Settings → Remote Sync.
  2. Enter a name, set Type to OpenVireo Sync Server, and fill in:
    • Server URL: http://127.0.0.1:8787, or your https:// 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
  3. Click Test Connection, then Save, then OK.
  4. 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.

See LICENSE.