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.
What Syncs
Section titled “What Syncs”- 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.
Requirements
Section titled “Requirements”- 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.
Turning It On
Section titled “Turning It On”- ChatShell asks about sync during first launch, or open Settings → Cloud Sync later and click Turn on sync.
- Click Set up encryption. ChatShell generates a sync passphrase and shows it exactly once.
- 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 Sync Passphrase
Section titled “The Sync Passphrase”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.
Security Model
Section titled “Security Model”- 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 Reference
Section titled “Settings Reference”Settings → Cloud Sync shows the current status plus manual controls:
| Control | What it does |
|---|---|
| Turn on sync | Starts onboarding (consent, passphrase setup, or joining an existing group) |
| Stop publishing | Keeps local data and merged history, but stops this device from uploading changes |
| Sync now | Runs a full sync pass immediately (pull, merge, publish) — also repairs a wedged engine |
| Force publish | Re-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 passphrase | Unlocks sync when the content key cannot be resolved automatically |
| Delete cloud data | Removes the encrypted snapshot and attachment store from iCloud Drive; other devices stop receiving updates |
Troubleshooting
Section titled “Troubleshooting”- “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.