Cloud Sync
Overview
Section titled “Overview”Cloud Sync keeps your Gridmux profile in sync across your own devices. You point each device at a personal remote (a private Git repo or storage bucket), and Gridmux keeps them up to date automatically.
Cloud Sync and Team Template are two modes of the same sync engine. Cloud Sync is the single-user mode — no roles, no team — for syncing one person’s setup across their machines.
What gets synced
Section titled “What gets synced”Gridmux syncs a fixed set of five profile files (the “bundle”):
aliases.json— your aliasessettings.json— your settingssession.json— your workspaces and layoutsrecents.json— recent projectsteam-notes.json— your notes
Only these files are synced — your project files and Git repositories are never touched.
Providers
Section titled “Providers”You can store the bundle on either:
- Git — a private repository (repo URL + branch). Authentication uses a Personal Access Token. The repo URL must be HTTPS (SSH is not supported).
- Cloudflare R2 — an S3-compatible bucket (endpoint + bucket + access key + secret key).
Credentials are kept in your operating system’s keychain — never written to
settings.json or into a repo’s .git/config.
Setting it up
Section titled “Setting it up”Open Settings → Cloud Sync and follow the 3-step wizard:
- Provider — choose Git or R2 and enter its details.
- Credentials — enter your token (Git) or access/secret keys (R2).
- Test connection — Gridmux verifies the connection before you finish.
Click Complete setup to finish. There is no role or identity step — Cloud Sync is single-user.
How syncing works
Section titled “How syncing works”Once configured, Gridmux keeps the bundle in sync:
- Automatically, on a timer (about every 5 minutes by default).
- When your profile changes (debounced).
- On demand, via the Sync now button.
Each cycle compares your local bundle with the remote and pushes or pulls as needed.
Override remote with this device
Section titled “Override remote with this device”If you want to force your current device’s bundle to become the source of truth, use Override remote with this device. This overwrites the remote bundle with your local state; your other devices receive that version on their next sync. You confirm in a dialog first. (Because Cloud Sync is single-user, every device is allowed to do this.)
Conflicts
Section titled “Conflicts”If both your local bundle and the remote copy changed since the last sync, Gridmux flags a conflict and asks you to pick a side — Keep local or Keep remote. Before overwriting, a snapshot of the remote bundle is saved locally, so the other side’s content isn’t lost.
Backups & restore
Section titled “Backups & restore”Gridmux keeps backups of your bundle before it overwrites it. Use Restore from backup… in the configured view to roll back to a saved version — a safety snapshot of your current state is taken first.
One mode at a time
Section titled “One mode at a time”A device is configured for either Cloud Sync or Team Template, never both at once. If Team Template is active, the Cloud Sync tab shows an inactive banner; Disconnect the other mode first to switch.
Notes & limitations
Section titled “Notes & limitations”session.jsonis made portable before syncing — live terminal process IDs are stripped on push, and your locally active workspace is preserved on pull.- The bundle is the same five files in both modes. If you previously used Team
Template, a
team-notes.jsonfrom that setup will also sync under Cloud Sync. Splitting “team” content from “personal” content is a known limitation deferred to future work.