Cloud Sync

Cloud Sync

Back up this PC's battery saves, memory cards and library database to a private GitHub repository. The repository is created automatically — no setup required beyond signing in. Every PC keeps its own repository, so a new or reinstalled PC can never overwrite progress made on another one — see One repository per PC.

The design matches the Windows app and uses the same repository format.

What Gets Synced

Data	Synced?	When
Battery saves (.srm)	Yes	On game close (upload) and game launch (download)
Memory cards and save folders	Yes	On game close (upload) and game launch (download)
Library database	Yes	During a full sync (app start, sign-in, "Sync Now")
Save states	No	Too large for some consoles (PSP/PS2/GameCube states can exceed 250MB)
HD texture packs, BIOS and system files	No	Not saves — they stay on this PC
Artwork / video snaps	No	Re-downloaded on demand from ScreenScraper / libretro
Screenshots / recordings	No	Local only

The library database includes your game metadata, ratings, favorites, collections, play time, per-game notes, and RetroAchievements cache — everything needed to rebuild your library view after a reinstall. Because your notes are stored in the library database, they're backed up with it automatically — no separate setup or upload.

Setup

1. Open Preferences → Backups
2. Click Sign in with GitHub
3. A code appears in the app (e.g., WDJB-MJHT) and your browser opens to github.com/login/device
4. Enter the code on GitHub and click Authorize
5. Done — a private repo named after this PC (e.g. emutastic-saves-gamingrig) is created under your GitHub account

You only sign in once. The sign-in and the encryption passphrase are kept in your desktop keyring (GNOME Keyring, KWallet or any other Secret Service provider, through libsecret) and persist across app restarts. Without a keyring they stay in config.json, which only your user can read, and Preferences says so.

Organization access: GitHub's authorization page may show an "Organization access" section if you belong to any orgs. Deny or ignore these — Emutastic only uses your personal account.

How It Works

On game close: Your battery save, and any memory cards or save folders the game wrote, are uploaded to this PC's repository. This happens silently in the background — you won't notice any delay.

On game launch: Before the core loads your save, Emutastic checks whether this PC's backup holds a newer copy than the local one (after a reinstall, for example) and downloads it if so. If your local save is already current, no download happens.

Sync Now: Click this button in Preferences → Backups to run a full bidirectional sync. This compares every save and the library database against this PC's repository, uploading anything newer locally and downloading anything missing or newer in the backup. Use it after a reinstall or after playing offline for a while. The status bar shows which step the sync is on and how many files have moved, and the same appears beside Sync Now. Pressing Sync Now while a sync is already running waits for that sync to finish.

Only changes transfer. A sync where nothing changed reports 0 up, 0 down. Downloaded files keep the timestamp they were uploaded with, so a file you only ever downloaded is never mistaken for a local edit. The library database is compared by content — your changes upload, a restored backup downloads, and an unchanged database transfers nothing.

One Repository Per PC

Every PC signed into your GitHub account backs up to its own repository, named after the PC (e.g. emutastic-saves-gamingrig). A PC never reads another PC's repository, so a new or reinstalled PC can't overwrite progress made elsewhere and never pulls in saves it didn't make. Signing in again on a reinstalled PC with the same hostname restores that PC's backup.

Earlier versions of the Windows app shared one emutastic-saves repository between PCs unless Make this PC unique was turned on. Neither app shares a repository any more, and the old shared repository is left untouched in your GitHub account.

Encryption (Optional)

By default, saves are uploaded as-is to your private repo. Since the repo is private, only you can see it. If you want an extra layer of security, enable encryption:

1. Check Encrypt saves before upload in Preferences → Backups
2. Enter a passphrase and click Save
3. All future uploads are encrypted with AES-256-GCM before leaving your machine

How it works under the hood:

• Your passphrase is combined with your GitHub username and run through PBKDF2 (100,000 iterations, SHA-256) to derive a 256-bit encryption key
• Each file is encrypted with AES-256-GCM, which provides both confidentiality and tamper detection
• The passphrase is kept in your desktop keyring on this PC — it never leaves your machine and is never sent to GitHub
• Encrypted files appear as .enc blobs in the repo — unreadable without the passphrase

After a reinstall: Enter the same passphrase in Preferences → Backups. Files are decrypted locally after download. A wrong passphrase produces a clear error — your local saves are never overwritten with garbage. Keep the passphrase somewhere safe: the backup can't be restored without it.

Changing your passphrase: If you need to change your passphrase, disable encryption, run "Sync Now" (uploads everything unencrypted), then re-enable with the new passphrase and sync again. There is no in-place re-encryption.

Turning encryption on or off later: The first sync after flipping the setting re-uploads your saves in the new format and automatically removes the old copies from the repo, so exactly one copy of each file ever exists remotely. Expect that one sync to take noticeably longer than usual — every file transfers once. (The removed copies remain recoverable through the repo's commit history.)

Viewing Your Saves on GitHub

This PC's repository is a normal private GitHub repository. You can browse it anytime at github.com/[your-username]/emutastic-saves-[hostname]. You'll see:

emutastic-saves-[hostname]/
  BatterySaves/
    NES/
      abc123.srm
    SNES/
      def456.srm
    ...
  library.[hostname].db
  manifest.json

The repository keeps the same hash-keyed BatterySaves/<Console>/ layout as the Windows app, even though the Linux session keeps its local saves under Saves/<Console>/. Each upload creates a commit, so you get full version history for every save file. If a save ever gets corrupted, you can revert to a previous version using GitHub's web UI.

Sharing Saves With Friends

Since your saves live in a standard GitHub repo, sharing is straightforward:

• Unencrypted saves: Make the repo public (Settings → Danger Zone → Change visibility) or add a friend as a collaborator. They can browse and download individual .srm files.
• Encrypted saves: Sharing the repo alone isn't enough — the recipient also needs your passphrase to decrypt the files.

This is a unique way to trade game saves — share your repo URL and a friend can grab your save file for a specific game and drop it into their own Emutastic data folder.

GitHub Storage & Limits

Limit	Value	Impact
Repo size (soft)	1 GB	Warning email from GitHub at 75%
Repo size (hard)	10 GB	Pushes blocked
File size	100 MB per file	No battery save comes close to this
API rate	5,000 requests/hour	A full sync of 500 games uses ~100 calls
Token lifetime	No expiration	Auto-revoked after 1 year of inactivity

In practice: Battery saves are typically 1–50 KB each. A library of 500 games with saves for every game would use ~25 MB of repo space. The library database adds another 5–15 MB. You would need tens of thousands of saves to approach the 1 GB soft limit.

Private repos are free and unlimited on GitHub — there is no cost for this feature.

Sync Timing Options

Configure in Preferences → Backups:

• On game close (recommended) — Uploads the battery save immediately after you close a game. Downloads happen automatically at the next launch.
• Every 15 minutes during play — Periodically uploads the current save during long sessions. Useful for RPGs where you don't want to lose progress to a crash.
• Manual only — Saves are only synced when you click "Sync Now."

Troubleshooting

First stop: the sync log. Every sync writes a line-by-line account to Logs/cloudsync.log in your data folder (~/.local/share/Emutastic/Logs/cloudsync.log) — what it plans to upload and download, its progress, what failed and why (including GitHub's rate-limit replies), and how long it took. See Log Files for details. If you report a sync problem, attaching this log is the most useful thing you can do.

"Not signed in" after reopening the app Your token may have been revoked (e.g., from github.com/settings/applications) or expired after 1 year of inactivity. Click "Sign in with GitHub" to re-authorize. If Preferences says the keyring could not be read, unlock it and restart Emutastic.

Sync fails with network errors Check your internet connection. Uploads and downloads fail gracefully — your local saves are never affected by a sync failure. Retry with "Sync Now" when connectivity is restored.

Wrong passphrase after a reinstall You'll see a decryption error. The download is aborted and your local save (if any) is preserved. Re-enter the correct passphrase in Preferences → Backups.

Texture packs or BIOS files missing after a restore They aren't part of the backup. Reinstall your HD texture packs, and put your BIOS and system files back in the System folder.

Which copy wins Emutastic uses last-write-wins: when a save differs between this PC and its backup, the copy with the more recent timestamp is kept on the next sync.