Self-hosted sync servers
Sync .kdbx files with a self-hosted server, no account needed.
Without an account, the SDK syncs ordinary password-protected .kdbx files with a self-hosted
OpenVireo Sync Server, the
same way the desktop app does. There are no vaults, no sharing and no keys beyond the database’s own
password: each database is one file under the user’s name on the server.
Pairing
Section titled “Pairing”A device gets a token of its own by claiming a pairing code from another device (Pair Device… in the
desktop app) or from the server (openvireo-sync-server devices pair alice):
import { SelfHostedSync } from "@openvireo/sdk";
const server = await SelfHostedSync.pair("https://sync.example.org", "ABCD-EFGH", "Web", { storage });
// next timeconst again = await SelfHostedSync.restore("https://sync.example.org", { storage });The token is kept in storage. Calling a server from a web app needs the server to allow the app’s origin
(SYNC_ALLOWED_ORIGINS, see the sync server’s
CORS section).
Syncing a database
Section titled “Syncing a database”import { decryptKdbx, passwordCredentials } from "@openvireo/sdk";
const { vault } = await decryptKdbx(fileBytes, password);const result = await server.syncDatabase("personal", await vault.saveLocal(), passwordCredentials(password));// result.kdbx is the merged file: save it locally and reopen it (result.report says what changed)The first sync of a database id uploads it. Later syncs download the server copy, merge it with yours against
the last common version, and upload the result, retrying on conflicts. The sync state (ETag, revision,
base copy) is kept in storage (the core’s offline cache), so give each device its own storage.
To keep a database openable without keeping its password (for example, sealed for a page reload), keep
await passwordHash(password) instead: the 32-byte password part of the KDBX key.
openKdbx(bytes, passwordHashCredentials(hash)) opens the file with it.
If another device changed the database’s password, the server copy doesn’t open with yours
(vault_key_mismatch): ask for the other password and sync with that.
Other calls
Section titled “Other calls”await server.health(); // '{"status":"ok"}'; not_sync_server for another siteconst databases = await server.listDatabases(); // [{ id, revision, etag, size, updatedAt }]const first = await server.download("personal"); // the .kdbx as uploaded, or null; opens with its passwordconst { code } = await server.createPairingCode(); // for the next deviceconst stream = server.events((e) => e.kind === "databaseChanged" && resync(e.databaseId));health() checks an address before pairing: a web page, a 404 or JSON that isn’t the sync server’s is
not_sync_server (with the page’s status), and an address that doesn’t answer is network_error.
download(id) fetches a database this device doesn’t have yet, without its password, to save as the first
local copy before the first syncDatabase.
server.history(id) and server.openVersion(id, revision, credentials) read earlier versions;
server.core is the core’s SelfHosted handle.