Black Candle Wiki / OpenMGMT / Syncing across devices
Syncing across devices
Local-first, sync optional
Sync is never required. The desktop app works entirely from its local SQLite database with sync disabled or no server configured — offline is a first-class state, not an error.
When you do sync, the protocol is OMGP/1: your device registers with the server, pushes its local events, pulls the account's event log, and replays remote events into the local database. Every replica converges on the same history.
Sign in with your Black Candle account
When the server has account auth enabled, device registration requires a Black Candle account. The desktop app uses the native OAuth flow (RFC 8252): it opens your system browser at the configured issuer, you log in or create an account, and the issuer redirects back to a loopback callback with an authorization code. The app exchanges the code with PKCE S256 and stores the access token in your OS keychain — never in the OpenMGMT database.
The access token is presented only at device-registration time. Normal push/pull sync uses the device token, so day-to-day sync never depends on the issuer being reachable. If the server ever stops recognizing a device token (for example its database was recreated), the client re-registers once per sync run, proving possession with the stored device token.
Run a sync
The desktop UI exposes sync from the Sync sidebar page — there is no background sync loop; you decide when to sync:
- Sync now runs one full cycle: device registration, push, pull, and remote replay. A second concurrent sync is rejected with
sync is already running. - Test connection sends only the OMGP/1 hello request to verify protocol compatibility. It registers nothing and moves no data.
- Clear sync error dismisses a stored sync error without changing the configured server.
The public sync server
Black Candle runs a public sync server at https://openmgmt.blackcandletech.com. Point the desktop app at it, sign in with your Black Candle account, and your devices share one event log.
Self-hosters can run their own server — the repository ships a docker-compose.yml, and the auth issuer is configurable, so any OIDC provider works for account auth.