Repository navigation
FAQ
Frequently asked questions about GSBS. If your question isn't here, check Troubleshooting or open an issue on GitHub.
GSBS is a self-hosted sync service — you run the server yourself, on your own hardware or a VPS. Your saves never touch a third-party cloud provider. Unlike Steam Cloud (which only works for games that opt in), GSBS works for any game whose save location is in PCGamingWiki, or any folder you point it at manually.
| Component | Supported |
|---|---|
| Server | Linux (amd64, arm64 via Docker) |
| Client | Windows (amd64), Linux (amd64) |
| macOS | Not officially supported |
Yes. The server supports many independent users, each with their own saves and multiple clients (e.g. desktop + laptop).
Yes, for games tracked by PCGamingWiki. GSBS derives a platform-neutral path_key so Windows and Linux saves for the same game converge to a single server slot. Proton/Steam Deck paths are resolved automatically. See How It Works → Cross-OS sync.
Yes. The client runs on Linux, and Proton compatdata paths are resolved automatically for Windows games running under Steam/Proton. You do not need to configure paths manually for PCGW-tracked games.
Docker Compose with Caddy (the default docker-compose.yml) is recommended. It handles HTTPS automatically and is the most battle-tested configuration. See Installation → Option A.
Port 443 (HTTPS) for client-to-server communication. If you run without TLS (local-only), port 8080. No inbound ports are needed on client machines.
Yes. Download gsbs-server-linux-amd64 (or the Windows binary) from GitHub Releases, set GSBS_SESSION_SECRET and GSBS_DB, and run the binary. See Installation → Option C.
No. Pin to a specific version tag (e.g. dendlomm/gsbs-server:2.0.0) so you control when schema migrations run and can roll back if needed. See Server Configuration.
- Temporarily set
GSBS_ALLOW_REGISTER=trueand restart the container. - Register the account via the WebUI.
- Set
GSBS_ALLOW_REGISTER=falseagain and restart.
Alternatively, create accounts via direct DB access (advanced).
- Confirm the game is installed via a supported launcher.
- If the launcher is installed in a non-standard location, add the folder override to
config.json(e.g.heroic_folder,steam_library_folders). - Tray → Rescan installed games.
- Check
discovery.jsonandgsbs.logfor launcher detection output.
The tray shows the reason next to each game. Common causes and fixes:
| Reason | Fix |
|---|---|
no_manifest_entry |
Run PCGW sync on the server |
save_dir_missing |
Launch the game once so its save folder is created |
wrong_platform |
Use Add a game manually… |
disabled |
Click the game in the tray to re-enable |
Run gsbs-client debug-sync <game_id> --dry-run for detailed diagnostics.
GSBS never creates save directories. When pulling a save, if the target folder doesn't exist (i.e. the game isn't installed on that machine), the save is skipped. This prevents writing orphan files to uninstalled game locations.
Yes. Tray → Discovered games → Add a game manually… — search the manifest or paste an absolute save folder path. This writes a watch_paths entry to config.json.
Weekly by default (Sunday 03:00). Admins can change the schedule in Admin → Settings (GSBS_PCGW_CRON env overrides the DB setting). Trigger a manual sync any time from Admin → PCGW → Sync.
Two scenarios:
-
fsnotify overflow: Many rapid changes can overflow the OS event queue. GSBS now triggers a directory rescan to catch missed events (
watcher_overflow_rescanin the log). -
Locked files: Games that hold exclusive write locks during save will cause push failures. The file is now enqueued to the outbox (
push_locked_file_enqueuedin the log) and retried once released.
The default conflict policy is last_write_wins — the most recently pushed save wins. Both machines' changes are recorded in conflicts.json. You can resolve conflicts from the tray or the WebUI dashboard (keep all local / use all server).
Change the policy in config.json:
{ "conflict_policy": "keep_local" }8 by default. Configurable via GSBS_SAVE_VERSION_RETENTION. Restore any version from WebUI Versions or the tray Open dashboard.
Saves are stored in plaintext by default. To enable encryption:
- Turn on End-to-end encryption in WebUI Settings.
- Set
"encryption_passphrase"in each client'sconfig.json.
With E2E encryption enabled, saves are encrypted locally with AES-GCM before being sent. The server never sees the passphrase or the plaintext. See Client Setup & Usage → E2E encryption.
Encrypted saves cannot be recovered without the passphrase. There is no server-side recovery. Back up your passphrase securely.
Yes, when you run the server behind HTTPS (recommended). The built-in Docker Compose setup uses Caddy for automatic TLS. Without HTTPS, communication is unencrypted — acceptable only on a trusted local network.
Yes — download only from the official GitHub Releases page. Verify the SHA256 checksum in SHA256SUMS if in doubt. Windows SmartScreen warning is expected for unsigned executables; choose More info → Run anyway.
The client checks GitHub Releases on startup (after 30s) and every 24 hours. When an update is available, it appears in the tray as Install update X.Y.Z…. The client downloads the binary, verifies the SHA256 checksum, replaces itself, and restarts. No re-running the installer needed.
Look in gsbs.log for lines prefixed with update: to see the actual result. Common statuses: network_error, api_error, metered_skip, manifest_mismatch. On Windows, metered_skip means the connection is flagged as metered — switch to an unmetered connection or disable the setting.
Yes. Set in config.json:
{ "update_repo": "your-org/your-fork" }See Upgrading → Backup procedure. The SQLite database is the single source of truth. With GSBS_SAVE_ROOT set, also back up that directory.
Password changes (and 2FA disable) revoke all active client tokens. Every client must re-login via tray Login… or gsbs-client login and create a new token.
Yes. Set GSBS_READ_ONLY=true. Push and delete are disabled; pull and read still work.
Yes, when GSBS_METRICS=1. GET /metrics returns Prometheus text format (request counts, storage, users, clients, saves). Guard with GSBS_METRICS_TOKEN in production. See API Reference → Metrics.
Yes. Any device that can run Docker (Synology DSM, Unraid, TrueNAS SCALE, etc.) can host the server. See the Unraid guide.
No. The server only needs to be reachable by the client at the configured URL. Clients can connect from anywhere over the internet (with HTTPS and your server URL).
Getting started
Reference
Help
Contributing