Omniscio

Export / import all data (backup ZIP)

The manual, on-demand export and import of your whole dataset as one ZIP — for moving to a new computer, snapshotting before a risky change, or restoring after a reinstall. Covers what the file contains, what it deliberately leaves out, how a full replace is made safe, and the compatibility rules on either side of a version change.

On this page

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.
  • Your Tasks files — the files Tasks agents wrote while doing a task and the documents you added to Tasks (Auto Context), as a tasks-workspace/ folder. Folders named node_modules and .git inside it are left out. Import puts them back by writing each file over the one at the same place on this computer.
  • The text you supplied to a machine-bound record — a few tables are kept OUT of the dump above because their row is tied to this computer (a local session id, a local commit sha, an absolute path) and a restore would copy rows onto a machine that never had them. The words YOU supplied in those rows still come out, as their own database/<table>.dsar.json file — for a code review, the plan or change you submitted. Nothing in the archive restores those rows anywhere, and where a machine detail sat inside the record you supplied (the folder the review was read from, the commit it was read at) it is left out too.
  • Your own cloud workspace data — when you are signed in, a cloud/account-data.json file carrying the part of your cloud account that is yours: your profile, every workspace membership you hold with its role, invitations you received and sent, the workspace activity-log rows about you, and your connections. It is built from your signed-in identity, never from anything the app can type into a request, and it deliberately leaves out other members' names and email addresses — a queued invitation shows the workspace and the date, never the address it was sent to. Only the activity rows that concern you are included, and that list is a bounded sample when you have an unusually long history; the file says so when it is cut short. Cloud chat messages and shared chat files are not part of this archive. This half is best-effort: if nobody is signed in the archive is exactly what it was before, and if the cloud cannot answer you get the local archive plus a plain sentence in README.txt saying which cloud details are missing and to export again while signed in.

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.
    • keeps everything the backup does not replace. Clearing a table used to take linked data in other tables with it: a learner's lesson progress, session tags, automations and their run history, knowledge-base links and versions. Omniscio now sets those linked rows aside first and puts them back once the backup is loaded, as long as what they belong to is still there. A row whose owner is genuinely gone from the restored data (a tag created after the backup, say) goes with it, as before. If a row could not be put back, the import says how many in a warning rather than losing it quietly.
  4. A toast reports how many records were imported, and stays on screen long enough to read — including any warnings about rows that were skipped. Omniscio then reloads its windows so every screen — sessions, tags, quick replies, bookmarks, automations, saved prompts and the rest — shows the restored data with no manual restart needed.

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. Since 2026-10-21 an agent may ask for any setting except a short refused set (secrets, plugin settings, sign-in, second factor, network allow-list, paywall and consent records, and the owner-only Pause all testing switch), which is refused before any card is raised; change those 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.)

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

Last verified 2026-11-09