Backup, restore, migrate

Polycode has no cloud sync and no account system. Your conversations, project links, model metadata, and preferences live in two folders on your Mac and nowhere else. That arrangement keeps the privacy story simple — there is no server-side copy for anyone to access — and it makes backup and migration a matter of moving two folders around. This article walks the three workflows step by step. For the precise mechanics behind each path, data lifecycle is the canonical reference.

Where your data lives

Two paths matter:

  • App Group container. Almost everything Polycode reads or writes lives here — the SwiftData store, the GRDB-backed FTS5 search index (which sits inside the same SQLite file), model-metadata caches, and your preferences (pinned models, fan-out opt-outs, tool-approval defaults) stored inside the SwiftData store under the polycode.prefs.* keys.

    ~/Library/Group Containers/group.com.izzo.polycode/Library/Application Support/Polycode/

  • Per-app sandbox. A small folder for macOS-managed preferences (@AppStorage toggles). Most settings live in the App Group blob above, not here, but the per-app sandbox is worth capturing if you want a pixel-exact restore.

    ~/Library/Containers/com.izzo.Polycode/

What is not in either folder: your API keys. Those live in the macOS Keychain, are bound to the Mac they were entered on, and do not travel with the container. Plan to re-enter keys on any new Mac. See the wipe section in data lifecycle for the full list of where credentials live.

Backup workflow

To capture a snapshot of everything Polycode persists locally:

  1. Quit Polycode with ⌘Q. Backups taken while the app is running can capture the SwiftData store mid-write; the cleanest snapshot is one taken with no writers attached.
  2. In Finder, press ⇧⌘G and paste ~/Library/Group Containers/.
  3. Copy the group.com.izzo.polycode folder somewhere safe — external drive, cloud folder, archive utility, whichever you prefer.
  4. Optionally, repeat for ~/Library/Containers/com.izzo.Polycode/ if you want the per-app sandbox’s preferences plist captured too.
  5. Relaunch Polycode. Your session resumes exactly as you left it.

If you’re using Time Machine, Arq, Backblaze, or any backup tool that walks the user library, both paths are captured automatically — there is no Polycode-specific exclusion or special-cased file. The manual workflow above is for the case where you want a one-off snapshot independent of a backup product, or where you want to move data between machines on a schedule the backup product isn’t running.

Restore workflow

To restore a previous backup over the current local state:

  1. Quit Polycode.
  2. In Finder (⇧⌘G), open ~/Library/Group Containers/.
  3. Either delete the current group.com.izzo.polycode folder or rename it aside (e.g. group.com.izzo.polycode.bak) so you can revert if the restore doesn’t look right.
  4. Copy your backup group.com.izzo.polycode folder into ~/Library/Group Containers/.
  5. If you also captured the per-app sandbox, repeat steps 3–4 for ~/Library/Containers/com.izzo.Polycode/.
  6. Relaunch Polycode.

Schema compatibility: the SwiftData store records its schema version inside the file. Polycode currently ships a single schema version with no migration stages, so a restored store whose schema doesn’t match the running build is copied aside and rebuilt rather than migrated (see below) — keep your own copy of the backup folder. Restoring a newer container into an older Polycode is not supported either; install the same version that wrote the backup.

Re-enter your provider API keys via Settings → Providers after a restore. Keychain credentials are bound to the Mac, not to the container, so a restored container starts with an empty key set even on the same machine.

Migrate to a new Mac

Migration is the backup workflow on one machine plus the restore workflow on another:

  1. Source Mac. Quit Polycode. Copy ~/Library/Group Containers/group.com.izzo.polycode/ (and, optionally, ~/Library/Containers/com.izzo.Polycode/) to portable storage — AirDrop to the new Mac is fastest for a few gigabytes; an external SSD or a sync folder works for larger stores.
  2. Destination Mac. Install Polycode from the Mac App Store. Launch it once so macOS creates an empty App Group container, then quit.
  3. Replace ~/Library/Group Containers/group.com.izzo.polycode/ on the destination with the copy from the source. If you brought the per-app sandbox, replace ~/Library/Containers/com.izzo.Polycode/ too.
  4. Launch Polycode on the destination Mac.
  5. Open Settings → Providers and re-enter your API keys. The Keychain is per-Mac; the keys never leave the source machine via this workflow.

Because nothing Polycode needs lives outside those two folders, the steps above are the complete migration procedure. There is no sync token to re-pair, no account to re-link, no remote handshake. The destination Mac has all the conversation history, project bindings, and preferences the source had — minus the credentials, which you bring back via the providers settings.

What schema-version compatibility means in practice

The SwiftData store records its schema version inside the file. Polycode currently ships one schema version and defines no migration stages, so there is no version gap it can bridge today: a store that doesn’t open under the running build’s schema takes the rebuild path, not a migration. A few practical implications:

  • A store that can’t be opened is rebuilt, not preserved in place. If a restored store fails to open, Polycode copies the store files to a timestamped sibling folder (named like Polycode.store.pre-rebuild-<timestamp>, next to the store inside the container’s …/Polycode/Store/ directory) and then rebuilds a fresh, empty store at the original path. Your original data survives only in that pre-rebuild copy — and Polycode keeps just the three most recent, pruning older ones after each rebuild — so keep your own copy of the backup folder before restoring. To recover, quit Polycode, restore your backup over the rebuilt store, and open it with the build that wrote it.
  • Restore into a build whose schema matches the one that wrote the backup. Because nothing migrates yet, treat a mismatch in either direction as a rebuild rather than an upgrade path.
  • If the copy-aside step itself fails, Polycode refuses to wipe. A full disk or an unwritable container aborts the launch instead of destroying a store it couldn’t back up first — a loud failure in preference to silent data loss. Free up space and relaunch.

For the SwiftData store internals — what each subdirectory holds and how caches differ from the canonical data — the backup section of data lifecycle is the reference.

What’s next

  • Data lifecycle — the canonical reference for every path, every cache, every credential surface in the app.
  • FAQ — short answers to common questions about how data moves and what stays on the Mac.
  • Getting started — for users newly arrived on the destination Mac, this is where install and onboarding lives.