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 (weekly encrypted bundle emailed to your Gmail) and 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 writes only inside the exports folder of your data directory (by default exports/omniscio-backup-<date>.zip); a path naming anything else, such as an app file like config.json, is refused so an export can never replace one of the app's own files. 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 or 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 — 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.
• 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; channels EMAIL_INBOUND_LIST_SENDERS (enumerate distinct stored senders) + EMAIL_INBOUND_ERASE_BY_SENDER (hard-delete by exact sender) → listDistinctInboundEmailSenders / eraseInboundEmailSenderLocalData in queries-email-inbound-erase.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 page, and the encrypted off-machine archive in a cloud-synced folder is on Backup Mirror; 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 is the seamless alternative, and the schema versions a restore is checked against are explained on database upgrades and migrations.

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