// OPENBOX DOCS
Statistics sync
Merge play statistics across machines through a mounted cloud folder.
OpenBoxGL merges play statistics between machines through any mounted folder, Syncthing, Dropbox, Nextcloud, Drive, or a plain local path. The folder must be mounted and writable on every machine that should participate.
Set it up
- In Settings → Integrations, set Mounted cloud folder to the absolute path of the mounted folder (for example
/mnt/cloud/openbox). - Click Sync statistics now to run a merge immediately. The Python fallback also runs a merge after each session; the 3.0 Rust server does not currently call that hook, so use the button until it is wired.
- Configure the same folder on another machine to merge stats there.
What syncs and how conflicts resolve
Sync reads and writes openbox-statistics.json (format 1) in the folder under a file lock. Per game:
| Field | Merge rule |
|---|---|
play_count, playtime_seconds | By maximum |
last_played | Newer timestamp wins |
progress, rating, favorite | Whoever played last is authoritative; if neither side has played, the newer file wins |
generated_at | Preserved when the remote was newer, bumped when local state is newer |
Deleted local games are never resurrected: games present only in the cloud file are dropped from the merged output, and only games that exist locally are written back. This keeps a removal on one machine from reappearing on another.
Troubleshooting
| Problem | Cause / fix |
|---|---|
"Configure a mounted cloud sync folder first." | No cloud_folder set in Settings; point it at a mounted, writable path. |
| Sync does nothing after a session | Check the folder is mounted and the file is writable; look for sync errors in the diagnostic log. |
| Stats reappear after deleting a game | Deletion does not remove the cloud file's entry for that game. Run a sync after deletion so the merged output drops it. |
Catalog sync
Statistics sync above covers play stats only. Catalog metadata travels through a separate opt-in transport: turn on Enable opt-in library catalog sync under Settings → Integrations after setting the mounted folder, then use Preview catalog changes (POST /api/v2/library/sync/preview), Apply reviewed changes (POST /api/v2/library/sync/apply), and Publish local changes (POST /api/v2/library/sync/publish). Launch paths, commands, credentials, play statistics, installed files, saves, and media stay on each device; the legacy whole-library publish/pull routes return 503 LIBRARY_SYNC_UNAVAILABLE.
See Library catalog sync for the workflow, conflict review, and the exact field allowlist.
See also
- Library catalog sync, opt-in catalog metadata sync (v1.10.0)
- Sessions, saves, and backups, session recording and history
- API saves and operations,
POST /api/v2/cloud/sync - Data and recovery, where local state lives