---
title: Export / import all data (backup ZIP)
---

# Export / import all data (backup ZIP)

## What it is

**The Backup & Restore panel's export and import** is the manual **export and import** of your entire Omniscio dataset as a single ZIP file. Use it to move Omniscio to a new computer, take a full snapshot before a risky change, or restore everything after a reinstall. It is the "save my whole app to a file / load my whole app from a file" feature, found at **Settings → Backup & Restore**.

One **Export Data** click writes a ZIP containing:

- **Your database** — every project, session, and the full conversation history, plus quick replies, auto-run (away-mode) rules, recipe-run history, SMS conversations and messages, spam rules and classifications, RSS feeds/items, webhook sources/messages, coaching state, automations and their run history, recipe schedules, and Slack conversations/messages.
- **Your settings and preferences** — your app settings, SSH remotes, muted-project list, and silence-until state.
- **Your global recipes** — every `.recipe.json` in your recipes folder.
- **Your attachments** — images and files you pasted into sessions.

**Account credentials and API keys are never included** in the export — the file is safe to copy to another machine, but it does _not_ carry your logins (you sign in again on the new machine).

A separate, smaller flow on the same page — **Settings Portability** — exports/imports _just_ your UI preferences (theme, keybindings, notification settings, etc.) as a small JSON file, with no project data, accounts, or keys.

> This page covers the **manual, on-demand** export/import. For the _automatic_ backup features that live on the same Settings page, see [setup-backup.md](setup-backup.md) (weekly encrypted bundle emailed to your Gmail) and [backup-mirror.md](backup-mirror.md) (encrypted archive written to a cloud-synced folder). Those run on a schedule and include session history too; the manual ZIP here is the one-click, full, unencrypted snapshot you trigger yourself.

## Where to find it

Everything on this page lives on one settings page — **Settings → Backup & Restore** — reached from the app's Settings gear. The export and import buttons sit together under that page's **Backup & Restore** card heading, the settings-only export and import are lower down that same page, and the sender-erasure list is at the bottom of the panel. There is no button for it anywhere else in the app.

## How it behaves

### How to use it

#### Export everything

1. Open **Settings → Backup & Restore** and click **Export Data**.
2. Click **Export Data** and choose where to save the ZIP.
3. A toast confirms how many records were written and the file size (e.g. `Exported 12,438 records (52,108 KB)`).

#### Import everything (replace all data)

Importing is a **full replace** — it wipes your current data and loads the backup in its place. Omniscio makes this as safe as it can:

1. In **Settings → Backup & Restore → Import Data**, click **Choose Backup File** and pick a ZIP you exported earlier.
2. Omniscio shows a **Backup Preview**: when it was created, the app version and platform it came from, the total record count, and a per-category breakdown — plus any **warnings** (see below). Nothing has changed yet; you can **Cancel** here.
3. Click **Replace All Data** and confirm the (irreversible) prompt. Omniscio then:
   - **stops every running session, on whichever engine runs it** — Claude's and every external engine's (the import rewrites the database underneath them). If any agent will not stop, the import is **refused** before anything is replaced, with *"Some agents did not stop, so nothing was changed. Stop them and try again."* — replacing the database under a live agent is exactly what must not happen, and a refused import can simply be retried,
   - **takes an automatic pre-import safety backup** of your current database (kept under your data folder; the last 3 are retained), and
   - replaces all data in one transaction and rebuilds the search index.
4. A toast reports how many records were imported. **Restart Omniscio** afterward to fully apply.

If anything in the file couldn't be read cleanly, you get plain-language warnings rather than a hard failure — e.g. "Some saved RSS items data was in an unexpected shape and was skipped," or "Skipped 4 sessions items that didn't match the expected format." The rest of the backup still imports.

#### Export / import only settings (Settings Portability)

Lower on the page, **Export Settings** writes a small JSON of your UI preferences; **Import Settings** previews how many settings will change and, on confirm, applies them. This carries no project data, accounts, or API keys — it's for syncing your _look and feel_ across machines.

#### Erase a sender's emails (privacy erase)

At the bottom of the panel, **Erase a sender's emails** lists every sender whose inbound emails Omniscio has stored — with a message count each — and permanently deletes one sender's stored messages, for a data-subject erasure request. It's a **pick-list, not a text box**: the app stores each sender exactly as the email header wrote it (often `Name <addr>`, and the exact format differs by provider), and the erase matches that stored value exactly, so choosing from the list is the only reliable way to hit the right rows. Click **Erase** next to a sender, confirm the red danger dialog, and that sender's stored messages plus their search-index copies are permanently removed — stored content only, never your files on disk, and with no Undo. A sender with nothing stored returns a clear "no stored emails found" rather than a confusing "erased 0."

### Compatibility and safety notes

- **Cross-version restores are allowed downward, blocked upward.** A backup from an **older** schema version imports fine (missing columns fall back to defaults, with a warning). A backup from a **newer** app version than you're running is **refused** — update Omniscio first, because importing newer-shaped data could corrupt the database.
- **Cross-platform restores warn about paths.** If the backup was made on a different OS (e.g. macOS → Windows), Omniscio warns that project folder paths may need updating.
- **A pre-import backup is always taken** before the replace, so a botched import is recoverable from the `backups/` folder in your data directory.
- **Crafted backups can't smuggle bad data in.** Imported settings are validated against the same schema the app uses (wrong-typed values are stripped); the highest-risk tables (sessions, conversation messages, projects) are row-validated; column names from the file are whitelisted against the real table columns so a malicious backup can't inject SQL; and recipe filenames are path-traversal-checked before any file is written.
- **Backward-compatible table renames are honored.** A backup that predates a table rename (e.g. the old `response_snippets` name for quick replies) still restores — Omniscio falls back to the legacy entry when the new one is absent.

### Scope and limits

- **Desktop UI, but reachable over the local control server.** The panel itself is part of desktop Settings, and the buttons are in-app actions — but the same two operations are live CLI routes on `http://127.0.0.1:19519`, so an agent or script can trigger them headlessly:
  - `POST /data/export` — writes the full-PII export ZIP. A `passphrase` is **required** (the CLI has no save dialog and there is no plaintext-ZIP fallback), and the ZIP is sealed at rest with PBKDF2 + AES-GCM. It is not approval-gated, but it takes the **full-trust CLI token** — an in-app agent session's scoped token is refused.
  - `POST /data/import` — **replaces all local data**, exactly as the in-app Import does. Always **approval-gated**: the route only enqueues, and the replace runs after you approve it in your inbox.
- **An agent can only ASK to import a settings backup.** The settings-only import has a CLI route, and it always waits for your approval. Its card lists every setting it would change, old value to new, and approving applies exactly those. Settings only you may change (the approval switch itself, sign-in, agent spawning, unattended landing, the load governors) are refused before any card is raised; change those with the import here in Settings.
- **The manual export is unencrypted.** It's a plain ZIP. If you need encryption at rest or off-machine durability, use [setup-backup.md](setup-backup.md) or [backup-mirror.md](backup-mirror.md) instead (both encrypt with a passphrase).
- **Import is all-or-nothing replace.** There is no selective "import only project X" from this flow. (The Backup Mirror's restore offers a _merge sessions_ mode; the manual ZIP import does not.)

## For agents

### Where things live (for agents with repo access)

- Service (export/preview/import + pre-import backup + plain-language warnings + per-row/column validation): [/src/main/services/backup/data-transfer-service.ts](/src/main/services/backup/data-transfer-service.ts) — `exportData()`, `previewImport()`, `executeImport()`, `createPreImportBackup()`.
- Settings UI (Export Data / Choose Backup File / Backup Preview / Replace All Data, plus the Settings Portability export/import): [/src/renderer/src/features/settings/sections/data-transfer/DataTransferSettings.tsx](/src/renderer/src/features/settings/sections/data-transfer/DataTransferSettings.tsx).
- IPC channels: `DATA_EXPORT`, `DATA_IMPORT_PREVIEW`, `DATA_IMPORT_EXECUTE`, and the settings-only `SETTINGS_EXPORT` / `SETTINGS_IMPORT_PREVIEW` / `SETTINGS_IMPORT_EXECUTE`.
- UI anchor for the Settings section: `settings-section-data-transfer`.
- Erase-a-sender's-emails card: [EraseSenderEmailsCard.tsx](/src/renderer/src/features/settings/sections/data-transfer/EraseSenderEmailsCard.tsx); channels `EMAIL_INBOUND_LIST_SENDERS` (enumerate distinct stored senders) + `EMAIL_INBOUND_ERASE_BY_SENDER` (hard-delete by exact sender) → `listDistinctInboundEmailSenders` / `hardDeleteInboundEmailMessagesBySender` in [queries-email-inbound.ts](/src/main/db/queries-email-inbound.ts). Both are blocked on the mobile/web bridge; UI anchor `erase-sender-emails-button`.

## Related

The automatic backups that live on the same settings page are the other half of this story — the weekly encrypted bundle emailed to your Gmail is on the [setup backup](setup-backup.md) page, and the encrypted off-machine archive in a cloud-synced folder is on [Backup Mirror](backup-mirror.md); both run on a schedule and both encrypt, which the manual ZIP here does not. If you are moving to a second computer rather than a second file, [Cross-Device Sync](cross-device-sync.md) is the seamless alternative, and the schema versions a restore is checked against are explained on [database upgrades and migrations](database-migrations.md).

- [setup-backup.md](setup-backup.md) — automatic, encrypted, weekly backup emailed to your Gmail
- [backup-mirror.md](backup-mirror.md) — automatic, encrypted off-machine archive in a cloud-synced folder (with a merge-restore mode)
- [database-migrations.md](database-migrations.md) — the schema versions a backup's compatibility check is measured against