Persist HELP CENTER
Help Center

Remote Storage

By default Persist saves each volume’s contents into its backing folder on your SSD. Remote storage changes where the saved snapshot lives: instead of the local disk, the same syncing machinery pushes the snapshot to an S3-compatible object storage bucket you own.

The idea is a durable, off-machine copy of your data that survives the Mac itself — handy for a machine that often travels, or for scratch space you still want to be able to recover after it’s gone.

Which providers are supported?

Persist talks to any S3-compatible object storage. The following providers are pre-configured in the app (and the same set is exposed by persist-cli remote list):

  • AWS S3
  • Cloudflare R2
  • Synology C2 Object Storage
  • Alibaba Cloud OSS
  • DigitalOcean Spaces
  • IONOS Object Storage
  • Scaleway Object Storage

All of them use the same model: a bucket (or “space”), plus an Access Key ID / Secret Access Key pair, and for some providers a region and/or a custom endpoint URL. The exact fields you fill in depend on the provider you pick — the app shows only the relevant ones.

How do I set one up?

From a volume’s detail view:

  1. Open the Remote options for the volume.
  2. Pick a provider from the list.
  3. Fill in the bucket, region/endpoint, and the access keys. Secret fields are never shown as plain text — the app prompts for them and stores them encrypted on disk (see below), so they never sit in the volume’s config file.
  4. Optionally set a path (a sub-folder inside the bucket).
  5. Validate the connection. The app verifies it can actually reach and write to the bucket before enabling remote storage.

Once configured and validated, the volume is set to use remote storage for its saves.

Note: the CLI can do the same thing, fully scriptable — see Command line. You pass the fields as command-line arguments; any required field you leave unset is prompted for (secrets are typed into a no-echo field).

Where does the data go when I eject?

The unmount-with-save flow works the same way as local saving, except the mirror target is your bucket instead of the SSD folder:

  • RAM → snapshot → remote bucket on eject/quit.
  • Periodic sync (if enabled) keeps refreshing the snapshot toward the bucket while mounted.
  • On the next mount, the content is restored back from the bucket into the RAM disk.

The three-copies model from How it works still applies — the third copy is just your bucket now, not a folder on the SSD.

What happens when there’s no network?

Remote saving needs a working connection. Persist degrades deliberately rather than losing your work:

  • Unmount with save, but the network is unavailable → the save falls back to a local snapshot. Persist copies the disk’s contents into its private on-disk snapshot (the ~/Library/Application Support/Persist/sync/.../latest-content/snapshot/ area) instead of reaching the bucket. It also records in its state file that the last save was forced local by the absence of network.
  • Mounting → Persist checks where the latest snapshot was made. If the most recent snapshot was made locally (because the network was down at that last save), it can restore from that local snapshot and mount normally. If the latest snapshot is only on the remote (the previous saves succeeded over the network), it must reach the network to restore — with no network, that mount is blocked rather than presenting an empty disk.

So the fallback is not “there’s always a local copy”. It’s triggered only when the last save actually landed locally (due to no network), and that local snapshot is what makes a future offline mount possible. The fix when a remote-only volume won’t mount offline is simply: restore network access and mount again.

What about privacy and credentials?

  • The bucket is private — Persist sets acl=private on objects it writes.
  • Credentials (Access Key ID / Secret Access Key) are stored encrypted on disk at ~/Library/Application Support/Persist/storage-credentials.json — an AES-GCM sealed file scoped to your Mac, not in the volume’s JSON config or the bucket. They are injected into the sync tool for each operation and never written to disk in plain text.
  • Only the computed remote name and non-secret settings (bucket, region, path) appear in the volume config file. See Per-Volume Options for where those live.

Remote storage never transmits your files’ contents anywhere but the bucket you configured — the data sits in a bucket you control.