Back up and restore local BoltAI data

Backup & Restore creates a portable, point-in-time copy of the BoltAI data stored on this Mac. Use it before moving to another Mac, reinstalling BoltAI, or making a major change to your setup.

Create a full backup

1. Open BoltAI → Settings → Backup & Restore.
2. Review the API-key protection status under Before You Back Up. If needed, select Enable Master Password… or Encrypt Existing Keys….
3. Select Create Full Backup….
4. Choose where to save the .boltai-backup file.
5. Review the sensitive-data warning, then select Create Backup.
6. Keep BoltAI open while it creates the database snapshot and packages your locally available attachments.
7. When the backup finishes, select Show in Finder or Done.

If BoltAI cannot find one or more referenced attachment files, the normal backup stops. You can select Retry, or explicitly choose Save Incomplete Backup. An incomplete backup cannot recover the missing files.

Restore from a backup

Restoring replaces all local BoltAI data on this Mac. It does not merge the backup with your current data.

1. Open BoltAI → Settings → Backup & Restore.
2. Select Restore from Backup….
3. Choose a .boltai-backup file.
4. Wait while BoltAI validates the archive, file hashes, database integrity, compatibility, and available disk space. Your current data is not changed during validation.
5. Review the backup date, chat, message, and attachment counts, plus any warnings.
6. Select Quit and Restore.
7. Open BoltAI again. The restore is applied before the database starts.
8. Return to Settings → Backup & Restore to review Last Restore. BoltAI also keeps a safety copy of the data that was on this Mac immediately before the restore.

If validation or startup fails, BoltAI keeps or restores the previous local data instead of continuing with a partial replacement.

Backup is not Cloud Sync

The key difference

• Backup & Restore: Creates a separate, point-in-time copy of the BoltAI database and attachment files available locally on this Mac. It does not contact BoltAI Cloud or download remote-only data.
• Cloud Sync: Keeps supported data up to date across devices. Changes and deletions can propagate to every synced device.
• Use both: Backup and Cloud Sync protect your data in different ways. Neither replaces the other.

What is included in a backup?

A full BoltAI backup contains:

• A consistent snapshot of the local BoltAI v2 database, including chats, messages, folders, prompts, agents, workflows, memories, and other data stored in that database
• Every locally available attachment file referenced by active BoltAI data
• A manifest used to check compatibility, completeness, and file integrity during restore

The backup does not include anything stored only in BoltAI Cloud. It also excludes caches, logs, downloaded models, general macOS preferences, licenses, sessions, saved passwords, and other device-specific Keychain data. Remote-only attachment files are not downloaded when you create a backup.

Keep the backup private

A .boltai-backup file is a normal, unencrypted ZIP archive. It may contain private conversations, attachments, provider headers, connector credentials, API keys, and other sensitive settings.

Master Password protects supported API keys stored in BoltAI, but it does not encrypt the entire backup. Store the file somewhere trusted or encrypt it with another tool.

What happens to Cloud Sync after a restore?

Restoring a backup changes only local data on this Mac. It does not upload the backup, delete cloud data, or roll BoltAI Cloud back to the backup date.

Cloud Sync stays off after restore. Any cloud-linked records found in the local backup are restored only as a local copy. If you later reconnect Cloud Sync, BoltAI asks you to Replace With Latest Cloud Data. This replaces the restored cloud-managed data on this Mac with the current copy from BoltAI Cloud; local-only accounts are not affected.

Some backups with cloud ownership that cannot be identified safely remain local-only, with Cloud Sync blocked for that restored copy.

Frequently asked questions

Does this back up my data in BoltAI Cloud?

No. Backup & Restore captures only the BoltAI database and attachment files available on this Mac. It does not connect to BoltAI Cloud or download data that exists only on the server.

If Cloud Sync is enabled, the local database may contain cloud-linked records that have already been downloaded to this Mac. The backup captures that local snapshot, not the current state of your BoltAI Cloud account.

Is Backup & Restore the same as Cloud Sync?

No. Sync keeps supported data aligned between devices. A backup is a separate point-in-time recovery copy. A mistaken deletion or unwanted change may propagate through sync, while an older backup remains unchanged until you replace or delete the backup file.

Does BoltAI create backups automatically?

No. Backups are currently created manually from Settings → Backup & Restore.

Does restore merge with my existing chats and settings?

No. Restore replaces all local BoltAI data on the Mac. Use BoltAI’s import feature when you want to add supported data without replacing the current database.

Can I restore a backup on another Mac?

Yes. Install the same BoltAI edition, either standalone or Setapp, and use the same or a newer BoltAI build than the one that created the backup. You may need to sign in, activate BoltAI, or reconfigure device-specific settings afterward because Keychain credentials, licenses, sessions, and general macOS preferences are not included.

If your API keys were protected with Master Password, enter the same Master Password on the other Mac to unlock supported keys. Otherwise, you may need to enter those credentials again.

Is the backup encrypted?

No. Treat every .boltai-backup file as sensitive. Store it in a secure location or encrypt it using a trusted storage or archive tool.

Can I store the backup in iCloud Drive, Dropbox, or another cloud drive?

Yes. The exported archive can be stored anywhere you choose, including an external drive or trusted cloud-storage folder. This does not turn it into Cloud Sync. The archive remains a separate backup file.

How often should I create a backup?

Create one before migrations, reinstalls, or other major changes. For ongoing protection, make backups regularly, keep more than one dated copy, and store at least one copy somewhere other than the Mac containing your BoltAI data.

Can I edit or extract the backup manually?

The archive uses ZIP internally, but you should not modify it. BoltAI verifies the manifest, expected files, sizes, hashes, and SQLite integrity. Modified or incomplete archives may be rejected.