> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinfoil.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud sync & encryption

> How Tinfoil Chat encrypts everything you sync with a key only you control, and how to set up sync with passkeys or a manual key backup.

Cloud sync backs up your chats, documents, projects, and settings so they follow you across the web app and the iOS app. Synced content is encrypted under your personal encryption key before it reaches persistent storage. Storage sees ciphertext and limited operational metadata, not your content.

## How it works

Cloud sync is built on two components:

1. **Your encryption key.** A 256-bit AES key generated on your device when you first enable cloud sync. It is displayed as a string starting with `key_`.

2. **The harness enclave.** All sync traffic goes through the hardware-isolated secure enclave that also runs your conversations, built from [open-source code](https://github.com/tinfoilsh/confidential-tinfoil-harness). Your app verifies its attestation and encrypts every request body to it before sending data. The enclave encrypts your content with your key and passes ciphertext and limited sync metadata to storage. When you chat in a local-only chat, your app sends that chat to the enclave with the request, and the enclave returns it without storing it.

The raw key is stored only on your devices (browser storage on web, the Keychain on iOS). Your app sends it to the harness enclave inside the encrypted body of each request that needs it. Because the harness enclave runs attested, publicly auditable code, you can verify that it uses your key only in memory and never stores or logs it. Background work such as imports and search-index rebuilds keeps the key in enclave memory until the job finishes. Passkey recovery stores only a wrapped copy of the key server-side.

> [!NOTE]
>
> If you lose access to your key, your data is unrecoverable — by design.
> Tinfoil has no master key, no recovery backdoor, and no way to decrypt your
> data for you. Set up at least one [backup option](#key-backup-options)
> before relying on cloud sync.

## What gets encrypted and synced

Every category of synced content is encrypted under your key. Local-only and temporary chats follow the separate behavior shown below.

| Data | Synced | Encrypted |
| - | - | - |
| Chats (full conversation content) | Yes | Yes in persistent cloud storage |
| Image attachments | Yes | Yes |
| Document attachments (stored as extracted text) | Yes | Yes |
| Projects: name, description, instructions | Yes | Yes |
| Project documents | Yes | Yes |
| Personalization: nickname, profession, traits, additional context | Yes | Yes |
| Custom system prompts | Yes | Yes |
| Prompt library entries and favorites | Yes | Yes |
| Preferences: theme, language, model settings, pinned chats | Yes | Yes |
| Local-only chats | Never | On iOS, encrypted with a device key; on web, cached without additional app encryption |
| Temporary chats | Never | Chat history is not persisted |

Chat titles and content are encrypted. Tinfoil stores limited operational metadata needed to sync encrypted data between devices. On the web, local chats and local caches of cloud data are not additionally encrypted by the app; rely on your browser and device protections.

> [!NOTE]
>
> Chat search is also private. The harness enclave maintains a per-user
> keyword and semantic index encrypted under a key derived from yours, so
> search works across encrypted chats without exposing their contents.

## Key backup options

Your key can be protected in two ways. You can use both at once.

### Passkeys (recommended)

A passkey (the credential behind Face ID, Touch ID, or your browser's passkey prompt) can protect your encryption key so you never have to handle it manually. Tinfoil Chat uses the open-source [Passkey Kit](https://docs.tinfoil.sh/guides/passkey-kit.md) library for this:

1. Your device uses the WebAuthn PRF extension to get a secret from your passkey.
2. Your device derives a wrapping key from that secret and uses it to wrap (encrypt) your chat encryption key.
3. Only the wrapped copy is stored server-side, never the raw key.

On a new device, approving one passkey prompt unwraps your key locally and cloud sync resumes. A passkey created in the browser can unlock the iOS app and vice versa, as long as your passkey provider (such as iCloud Keychain) syncs it between devices.

You can register multiple passkeys (one per device or platform) that all protect the same key. Cloud Sync settings list these under **Registered platforms** on web and **Recovery methods** on iOS. Removing a recovery method from Tinfoil does not delete the passkey from the operating system.

### Manual key backup

If you prefer not to use passkeys, save a copy of the key itself. Tinfoil Chat offers three formats:

* **Copy the key string** (`key_...`) to a password manager or other secure location.
* **Download a PEM file** (`tinfoil-chat-key-<date>.pem`) and store it somewhere safe.
* **Show a QR code** on one device (web) and scan it from the iOS app.

To restore on another device, paste the key string, upload the PEM file, or scan the QR code during setup.

> [!WARNING]
>
> Do not share your key with anyone, and only store it in a secure location.
> Anyone with your key and access to your account data can decrypt your
> chats.

## Set up cloud sync

> [tab] Web app
>
> ### Enable cloud sync
>
> 1. Sign in at [chat.tinfoil.sh](https://chat.tinfoil.sh).
> 2. Open **Settings** (gear icon in the sidebar) and select the **Cloud Sync** tab. You can also navigate directly to [chat.tinfoil.sh/#settings/cloud-sync](https://chat.tinfoil.sh/#settings/cloud-sync).
> 3. Turn on the **Encrypted Cloud Sync** toggle.
> 4. In the setup dialog, click **Continue**. If your browser supports passkeys, you'll be prompted to create one. This generates your encryption key and protects it with the passkey in one step.
> 5. Without a passkey, choose **Generate Encryption Key** instead, then save the displayed key using **Download** (PEM file) or **Copy** before clicking **Let's go!**.
>
> ### Set up a passkey later
>
> 1. Go to **Settings → Cloud Sync**.
> 2. In the **Passkey** section, click **Add Passkey for seamless sync** (or **Set Up Passkey on This Device** if your other devices already use one).
> 3. Approve the passkey prompt.
>
> ### View or copy your key
>
> 1. Go to **Settings → Cloud Sync**.
> 2. Under **Your Personal Encryption Key**, use the eye icon to reveal the key, click the key to copy it, or use the **QR code** and **Download** buttons.
>
> ### Restore your key on a new browser
>
> 1. Sign in and open **Settings → Cloud Sync**, then turn on cloud sync (or click **Set Up Cloud Sync** in the sidebar).
> 2. If you have a passkey, click **Unlock with Passkey** and approve the prompt. Done.
> 3. Otherwise, choose **Restore Encryption Key**, then paste your `key_...` string or upload your PEM file, and click **Restore Key**.

> [tab] iOS app
>
> ### Enable cloud sync
>
> 1. Sign in, open the sidebar, and tap **Settings**.
> 2. Under **Chat Settings**, tap **Cloud Sync**.
> 3. Turn on the **Cloud Sync** toggle. If you already have a passkey from another device, the app unlocks your key automatically with Face ID or Touch ID.
> 4. For first-time setup, tap **Continue**, then **Generate Key**. Save the displayed key with **Save to Files** or the copy button, then tap **Done**. If a passkey was created during setup, the key is protected automatically and this step is skipped.
>
> ### Set up a passkey later
>
> 1. Go to **Settings → Cloud Sync**.
> 2. In the **Passkeys** section, tap **Add Passkey for seamless sync** (or **Set Up Passkey on This Device**).
> 3. Approve with Face ID or Touch ID.
>
> ### View or copy your key
>
> 1. Go to **Settings → Cloud Sync**.
> 2. In the **Encryption** section, tap the copy button next to **Current Key**, or tap **Reveal Backup Key** (passkey users) to display the full key. **Current Key** uses the normal system clipboard. Copies made from **Reveal Backup Key** expire after five minutes.
>
> ### Restore your key on a new device
>
> 1. Enable cloud sync as above. If a passkey is available, the app recovers your key automatically.
> 2. Otherwise choose **Restore Encryption Key**, then either type or paste your `key_...` string, import your `.pem` file, or tap **Scan QR Code** and scan the QR code shown in the web app's Cloud Sync settings. Tap **Restore Key**.

## If you lose your key

If you lose both your key backup and all passkeys, your encrypted data cannot be recovered. **Start Fresh** generates a new key so you can keep using cloud sync, but it cannot recover data encrypted with your old key.

To avoid this situation:

* Set up a passkey on at least one device with a synced passkey provider (such as iCloud Keychain).
* Keep a copy of the key string or PEM file in a password manager.
* Both together give you two independent recovery paths.

## Next steps

> [card] [Data controls & deletion](https://docs.tinfoil.sh/chat/data-controls.md)
>
> Local-only chats, temporary chats, exporting, and deletion behavior.

> [card] [Passkey Kit](https://docs.tinfoil.sh/guides/passkey-kit.md)
>
> The open-source library behind Tinfoil Chat's passkey-protected keys.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.