Cloud Sync

Cloud Sync

Sync your battery saves and library database across multiple machines using your GitHub account. A private repository is created automatically — no setup required beyond signing in. Machines can also opt out of sharing and keep their own private cloud backup instead — see One shared repo, or one per machine.

The design is identical to the Windows app and uses the same repo formats, so a Linux install and a Windows install signed into the same GitHub account interoperate — saves and your library follow you between them.

What Gets Synced

Data	Synced?	When
Battery saves (.srm)	Yes	On game close (upload) and game launch (download)
Library database	Yes	During "Sync Now" (full bidirectional sync)
Save states	No	Too large for some consoles (PSP/PS2/GameCube states can exceed 250MB)
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 on a second machine. Because your notes are stored in the library database, they sync across machines 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 called emutastic-saves is created under your GitHub account

You only sign in once. The token is stored securely on your machine and persists across app restarts.

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 (.srm) is automatically uploaded to the emutastic-saves repo. This happens silently in the background — you won't notice any delay.

On game launch: Before the core loads your save, Emutastic checks whether the remote save is newer than the local one. If you played on another machine since your last session here, the newer save is downloaded automatically. 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 battery save and the library database against the remote, uploading anything newer locally and downloading anything newer remotely. Use this when setting up a second machine or after playing offline for a while.

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, and each machine tracks what it last synced — your changes upload, another machine's changes download, and an unchanged database transfers nothing.

One Shared Repo, or One Per Machine

By default every machine signed into the same GitHub account shares one repository (emutastic-saves), which is what makes saves and your library follow you between machines.

If you don't want a particular machine to participate in that — a kids' PC, a test machine, a machine whose library you deliberately keep different — turn on Make this PC unique — don't share saves or library with other PCs in Preferences → Backups. That machine then backs up to its own repository, named after the machine (e.g. emutastic-saves-gamingrig):

• Its saves and library database are still backed up to the cloud
• They stay unique to that machine — they won't appear on your other machines, and your other machines can never overwrite them
• The setting is per-machine: each machine decides for itself, and flipping it never deletes anything — both repositories remain in your GitHub account

Turning the toggle off rejoins the shared repository, with the normal newer-wins rules deciding what transfers on the next sync.

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 stored locally on your machine — it never leaves your machine and is never sent to GitHub
• Encrypted files appear as .enc blobs in the repo — unreadable without the passphrase

On a second machine: 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.

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

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

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

The repo keeps the same hash-keyed BatterySaves/<Console>/ layout the Windows app uses, which is what lets the two interoperate — even though the Linux session writes its local saves RetroArch-style as Saves/<romstem>.srm. 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.

Machines using the per-machine option have their own repository alongside it, named emutastic-saves-[machine-name], with the same layout.

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 was uploaded, downloaded, removed, or failed and why. 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.

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 on a second machine 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.

Save conflict (played on two machines offline) Emutastic uses last-write-wins: the save with the more recent timestamp takes priority. If you played on machine A and machine B without syncing between them, the most recently modified save overwrites the other on the next sync.