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. When Polycode launches and finds an older schema than the current build expects, it migrates forward when the gap is one it can bridge; if it can’t, it rebuilds a fresh store (see below), so keep your own copy of the backup folder. Restoring a newer container into an older Polycode is not supported — install the same version (or newer) 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, and schema versions migrate forward in sequence on first launch under a newer build. A few practical implications:

  • A store that can’t be migrated is rebuilt, not preserved in place. If a restored store fails to open on a newer Polycode build, Polycode copies the store files to a timestamped sibling folder (named like PolycodeStore.pre-rebuild-<timestamp>, next to the store) and then rebuilds a fresh, empty store at the original path. Your original data survives only in that pre-rebuild copy — 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 a build whose schema matches (or is newer than) the one that wrote it.
  • Restore into a build whose schema is the same as, or newer than, the one that wrote the backup. Polycode is pre-1.0 and there is no documented cross-version skip guarantee yet — across a gap it can’t bridge, the store is rebuilt rather than migrated.
  • When a migration does run, it runs once on the launch that needs it; subsequent launches start fast.

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.