// OPENBOX DOCS

Save discovery and restore

Discover save locations, create versioned backups, and restore safely.

OpenBoxGL can discover where a game keeps its saves, back them up into versioned archives, and restore them with hard safety checks. This page covers the practical workflow: find saves, back them up, restore them, and recover when a restore is refused.

Before you start

The game must have a local file (path) so OpenBoxGL can identify it.
Saving works per game from the Save management section of the detail pane, or library-wide from the Health dialog (Scan library for saves).
Optional tools on PATH: Ludusavi and Hoard add external save-tool actions.

Discover save locations

Open a game's Save management and choose Discover locations. OpenBoxGL looks in the common places for each platform:

Platform	Location checked
Steam Cloud	`~/.local/share/Steam/userdata/*/<appid>/remote` (also `.steam/steam` and the Flatpak path)
PlayStation 2	PCSX2 `memcards` (native and Flatpak)
PSP	PPSSPP `PSP/SAVEDATA`
PlayStation 3	RPCS3 `dev_hdd0/home/00000001/savedata`
GameCube	Dolphin `GC`
Wii / WiiWare	Dolphin `Wii/title`
Wii U	Cemu `mlc01/usr/save`
Sega Saturn	RetroArch `saves` (or `~/.mednafen`)
RetroArch	any save or state file under `saves`/`states` whose stem matches the game name

Candidates are shown as path + label + shared. Confirm them per game, or run Scan library for saves to apply discovered paths to every game at once. Confirmed paths are stored on the game (save_paths) and drive the library's Has saves view.

Back up saves

Back up now creates a ZIP per game under <data-dir>/save-backups/<hash>/ named YYYYmmdd-HHMMSS-<label>.zip containing a manifest.json and the configured save roots. Details:

Files are backed up individually; directories are walked.
Symlinks in save paths or the backup directory are refused.
After each backup, Save backup retention limit (0-500, default 10) trims the oldest archives.
Back up saves when a game session ends creates an on-close archive automatically and enforces the same retention.

The CLI form is python3 web_app.py --backup for whole-library backups; per-game save backups are a UI/API operation (POST /api/saves/backup).

Restore saves

Restore validates hard before writing anything:

An automatic before-restore backup of the current saves is created first.
The archive's manifest roots must match the game's currently configured save_paths exactly (count and order). If you edited the save paths after the backup, restore refuses with "Save backup roots do not match this game.", restore the paths to the archived values, or make a new backup.
Members are validated: no absolute paths, no .., no duplicates, no symlinked destinations, per-member cap 4 GiB, total cap 32 GiB.
Files are written with mode 0o600 through atomic copy.

Restoring is destructive by design, the before-restore archive is your safety copy.

Ludusavi and Hoard

Optional CLI save tools found on PATH:

Ludusavi: backup, restore, backups, find, run with --api JSON output and --force; an optional --path comes from the game's ludusavi_backup_path.
Hoard: backup, restore, list; backup/restore accept a game name.

Both treat restore as destructive (they overwrite local files), so run a backup first and verify the tool's own report.

Troubleshooting

Problem	Cause / fix
`"No configured save paths currently exist."`	The game has no discovered/confirmed save path. Run Discover locations or add one manually in Save management.
`"Save backup paths may not be symlinks."`	A configured save path is a symlink; point `save_paths` at the real directory.
`"Save backup roots do not match this game."`	The game's `save_paths` changed after the backup. Restore the archived paths (or back up again).
`"Save backup not found."`	The archive name is not inside the game's backup directory; use a name from the backup list.
Restore does nothing / files missing	Check the diagnostic log; restores refuse symlink destinations and paths outside the data directory, and write `0o600`.