// OPENBOX DOCS

Data and recovery

Understand schema version 7 state files and recovery behavior.

The library is one schema-versioned JSON file with a last-known-good sidecar, cross-process locking, and atomic owner-only writes. This page documents the exact layout, the migration path, stable IDs, caps, and recovery.

File layout

Inside the data directory (default ~/.local/share/openbox-game-launcher, or OPENBOX_DATA_DIR):

PathPurpose
library.jsonThe primary state: format (openbox-library), schema_version (7), games, profiles, history, settings, playlists, queue, notifications, ui_state, trash, party_decks, emulator_settings, achievement_overrides, deals, time_capsules, itinerary
library.json.bakLast-known-good copy, rewritten before every commit
library.json.snapshots/Rolling snapshots of the last 5 committed states, kept as timestamped JSON copies for point-in-time recovery
.library.json.lockCross-process flock lock coordinating concurrent writers
sessions.jsonActive sessions mirrored out of the library (format 1) for crash recovery; reconciled at startup and removed when no sessions remain
library.v6.backup.jsonPre-migration copy of the v6 library, written by openbox --migrate-library (or by a 2.0/2.1 first start). OpenBox 3.0 does not restore it; use OpenBox 2.1.0.
migration-report.jsonRecord of the v6→v7 migration (counts, sessions moved)
migration-in-progress.jsonCrash marker present while a migration runs; a leftover marker lets startup reconstruct the report
migration-acknowledged.jsonRecords that the user has seen the migration report
rollback-report.jsonLegacy 2.0 record of a rollback. 3.0 never writes it.
media/manifest.jsonPer-file SHA-256, size, and mtime for downloads and captures, feeding the integrity check
server.token, server.portPer-launch credentials for the running Web UI; deleted on exit

Catalog synchronization is separate from this local state directory. When enabled, immutable events live under <cloud_folder>/openbox-library-v3/ in the mounted folder selected in Settings. The v3 transport does not copy launch paths, commands, credentials, statistics, saves, or media.

Write path

The Rust JsonStateStore (crates/openbox-store/src/json_store.rs) commits like this. The Python state_store.py implementation mirrors it for the fallback.

  1. Serialize with compact JSON when the pretty-printed payload exceeds 1 MiB (COMPACT_JSON_THRESHOLD) or the library exceeds 500 games; pretty-printed below it; always write a trailing newline.
  2. Write to a temp file in the same directory, fsync it, chmod 0o600.
  3. Staged atomic backup: write to temporary backup file and os.replace over library.json.bak, chmod 0o600.
  4. os.replace the primary temp over library.json, chmod 0o600, then fsync the directory.

Every read and write happens under the file lock, so two OpenBoxGL processes (Web UI and native UI) can share one library safely. The last writer wins per transaction, not per file. Loaded state is deep-copied per request, so callers cannot mutate the cache by accident.

Schema versions and migration

The current schema is version 7 (STATE_SCHEMA_VERSION). 3.0 does not migrate on open. Schema 7 opens directly; schema 6 raises STATE_SCHEMA_TOO_OLD and is left unchanged until openbox --migrate-library runs; schema 1-5 must be opened once on OpenBox 2.1. The historical migration chain is:

FromMigration
v1→v2Wrapped into a state object, gains profiles, history, settings, playlists
v2→v3Index-suffixed IDs (game-<24 hex>-<n>) are replaced by stable IDs; the old ID moves into legacy_game_ids as an alias
v3→v4Gains queue and notifications, capped at 500 and 200 entries; non-list game tags become []
v4→v5Gains the host-owned ui_state block; games, settings, playlists, and history are unchanged
v5→v6Gains the active_sessions collection used to reconcile running sessions across restart
v6→v7Adds the "format": "openbox-library" envelope; active_sessions move out to sessions.json; the pre-migration file is kept as library.v6.backup.json

Unknown fields survive migration; only known collections are normalized. A schema above 7 raises STATE_FUTURE_VERSION and is never rewritten. A schema below 7 raises STATE_SCHEMA_TOO_OLD on open; openbox --migrate-library is the only writer for schema 6, and schema 1-5 must be opened on OpenBox 2.1 first. Invalid JSON or a missing games collection raises STATE_UNAVAILABLE/corrupt-state handling. A complete v7 object takes a fast path without normalization.

openbox --rollback-library was removed in 3.0. It exits 4, changes no file, and names OpenBox 2.1.0 as the build that restores library.v6.backup.json.

Stable game IDs

game_id is derived from game identity, never list position: SHA-256 over a sorted JSON payload of path (normalized), platform, steam_app_id, heroic_app_id, lutris_id, gameyfin_id, launchbox_db_id, or name when no store id exists, plus gog_id, ea_id, and ubisoft_id when those values are non-empty, truncated to 24 hex characters and prefixed game-. Collisions append -2, -3, ... Deterministic from identity, so reordering, deleting other games, and re-importing do not change which entry a queue item, save backup, or history entry points at. Legacy indexed IDs are retained as legacy_game_ids aliases and accepted by the API.

Caps

  • queue: at most 500 entries; oversized or non-list values are capped/replaced on load.
  • media-queue.json: at most 5,000 items; new enqueues are refused once full.
  • notifications: at most 200 entries, newest first.
  • history: capped at the last 500 sessions when session history is enabled.
  • Per-game tags: 50 tags, 64 characters each (see API automation).
  • save_paths: at most 50 entries per game; screenshots: at most 100; alternate_names: at most 20; applications/versions/documents: at most 100 entries each (extra name defaults to the path stem).
  • custom_fields: capped per custom_field_defs (up to 20 defs); list_columns: at most 12; hidden_sidebar_sections: at most 20.
  • smart_collections: at most 50 named {name, query} shelves at write time (v1.12.0); names cap at 80 characters, queries at 500.

Other durable files

Not everything durable lives in library.json, and these files are not covered by its transaction:

PathContent
media-queue.jsonDurable media download queue. A JSON list written atomically with mode 0o600 under its own .media-queue.json.lock; at most 5,000 items, and it survives a restart independently of the state store
native-host-recentPrivate recent-game list written at boot and refreshed after sessions, one name<TAB>game id line per entry, capped at eight so the Linux, Windows, and macOS tray menus can offer recent games
cache/launch_audit.jsonThe latest Launch Audit report used by readiness badges (not library state)
cache/launch_audit.jsonlCompact rolling launch-audit history, rotated at 5 MiB so trend checks stay bounded

Save manifests are not a separate data file: each save backup archive carries a manifest.json recording every file's size, mode, mtime, and SHA-256. The version-history and selective-restore dialogs read that manifest from the archive.

Corruption and recovery

If library.json fails to decode (invalid JSON, wrong type, game without identity, invalid games collection), the original file is preserved untouched and StateCorruptError is raised. The API answers 503 with {"error":"OpenBox library data needs recovery before this operation can continue."} until you recover.

Recovery (/api/v2/state/recover or recover_state()) requires authentication and replaces the primary with the .bak copy:

  • If no .bak exists: "No last-known-good state exists at <bak path>."
  • If the backup is also unusable: "The last-known-good state is also unusable: <bak path>"
  • Otherwise the backup is normalized, written through the same atomic path, and the API returns {"ok": true, "games": <count>}.

The .bak is always at least as fresh as the primary commit that preceded the last write, because it is written before the swap.

Dry-run and snapshots

/api/v2/state/recover accepts two extensions beyond the bare restore:

  • {"dry_run": true} previews recovery without touching the file: it reports whether .bak exists, lists the available snapshots, and returns the current game count.
  • {"snapshot": "<name>"} restores a named snapshot from library.json.snapshots/ instead of the backup. Snapshot names are strictly the file names inside that directory; anything else is rejected.

Snapshots rotate on every commit: the last 5 committed states are kept as timestamped JSON copies, so a bad edit can be rolled back to a point in time even when .bak already reflects it.

Since 1.16.1 the newest snapshot is reliably the one you want. Rotation prunes in the order the snapshots are listed rather than by modification time — timestamps can tie, and a tie previously let rotation delete the newest recovery point — and snapshots are listed newest first. A full commit also discards any snapshot still queued from before it, rather than writing a stale snapshot over the newer commit.

Security notes

  • All state files are owner-only (0o600), including the backup and lock.
  • Back up the whole data directory before manual intervention: library.json, the sidecar, media, backups, and settings move together.
  • Exported library data and local paths are sensitive; keep library.json exports private.
  • The application state store is crates/openbox-store/src/json_store.rs (Python state_store.py is the fallback). tests/test_state_v4.py and the Rust store tests are the maintenance sources.