Skip to content

Cross-Device Sync

ChatShell can keep your history consistent on every device you own — conversations, assistants, prompts, and attachments. Sync runs through the iCloud Drive folder you already have: there is no ChatShell server, and the cloud copy is encrypted with a key that never leaves your devices.

The iPhone and iPad app is in beta on TestFlight (iOS or iPadOS 18 or later). Sync works between Macs and with the beta app.

  • Conversations — messages, tool calls, and thinking steps, with full history
  • Assistants — personas, prompts, and configuration
  • Prompt library — categories, starred prompts, and contents
  • Attachments — files and images, stored as content-addressed encrypted blobs

Merging is record-level: each device publishes its changes and every device converges to the latest version of each conversation, assistant, prompt, and attachment. Editing on two devices at once is safe — the newest change to each record wins.

  • An iCloud account signed in on every device (iCloud Drive must be available)
  • The same Apple ID on all devices joining the same sync group
  • ChatShell on each device

Everything also works fully offline with sync off — sync is an addition, never a dependency.

  1. ChatShell asks about sync during first launch, or open Settings → Cloud Sync later and click Turn on sync.
  2. Click Set up encryption. ChatShell generates a sync passphrase and shows it exactly once.
  3. Save the passphrase in a password manager or write it down, then confirm. Sync starts running in the background.

On a device that joins an existing synced history (for example a second Mac), ChatShell attempts to pick up the encryption key from iCloud Keychain automatically. If that is not possible, it asks for the sync passphrase instead — entering it joins the group and pulls your cloud history.

The passphrase unwraps the encryption key for your cloud history on devices that cannot obtain it from iCloud Keychain.

  • It is not recoverable from the app. Write it down or store it in a password manager when it is shown.
  • If you lose it, devices that are already enrolled keep working, but the cloud backup cannot be restored anywhere new.
  • If ChatShell cannot resolve the key, a non-blocking banner appears — everything on the device keeps working, and entering the passphrase unlocks your cloud history.
  • End-to-end encrypted transport. Snapshots and attachment blobs travel as ciphertext (AES-256-GCM). Anyone with access to the cloud folder — including the folder-sync provider — sees only encrypted data.
  • Keys stay on your devices. The content key is shared through iCloud Keychain or wrapped under your passphrase; it never leaves your devices in plaintext.
  • Credentials are double-wrapped. Provider API keys ride the snapshot only as an additional layer of ciphertext under their own key.
  • Turning sync off does not delete anything. Use Delete cloud data in settings to remove the encrypted snapshot and attachment store from iCloud Drive. Data on your devices is untouched.

Settings → Cloud Sync shows the current status plus manual controls:

ControlWhat it does
Turn on syncStarts onboarding (consent, passphrase setup, or joining an existing group)
Stop publishingKeeps local data and merged history, but stops this device from uploading changes
Sync nowRuns a full sync pass immediately (pull, merge, publish) — also repairs a wedged engine
Force publishRe-sends this device’s full state to iCloud even if sync thinks it is up to date. Use it when another device is missing recent changes
Enter passphraseUnlocks sync when the content key cannot be resolved automatically
Delete cloud dataRemoves the encrypted snapshot and attachment store from iCloud Drive; other devices stop receiving updates
  • “That passphrase doesn’t match” — check the phrase you saved when sync was first enabled on your first device.
  • “Synced data appears damaged or written by a newer version” — update ChatShell to the latest version on every device and retry.
  • A device is missing recent changes — run Sync now on the device that made the changes, then Sync now on the other device. If changes are still missing, use Force publish on the source device.