Portable Backup (one-file encrypted export/import)

What it is

Portable Backup is a one-file encrypted backup you create at Settings → Backup & Restore → Portable Backup and carry to another computer yourself — on a USB stick, in a cloud drive, over email — rather than relying on a continuously-synced shared folder. It writes a single .amcbackup file containing your whole database (every project, session, and conversation), your config, and your attachments, encrypted so the file is safe to store or send anywhere. On the destination machine you pick the file back up and Omniscio figures out how to apply it: a full restore on a brand-new install, or an additive merge (nothing overwritten, nothing deleted) if that machine already has data.

How this differs from Omniscio's other backup features: backup-mirror.md writes continuously to a folder you point at a cloud-sync client (Dropbox/ OneDrive/iCloud) and stays in sync automatically — no code to remember, but it needs that shared folder set up on both machines first. setup-backup.md emails a small, config-only bundle weekly (no chats). data-transfer.md's manual export/import ZIP is unencrypted and always a full replace. Portable Backup is the one-off, encrypted, "hand someone a single file" option — no shared folder needed, and it auto-detects whether to replace or merge based on whether the destination already has data.

Where to find it

Portable Backup lives at Settings → Backup & Restore → Portable Backup and is shipped — visible to everyone, with no Lab row to turn on and no env flag to set. portableBackupEnabled survives in AppSettings as a leftover: the only thing that still reads it is the off-machine-backup heuristic in src/shared/backup-mirror-activation.ts, never a visibility gate.

How it behaves

How to use it

Export a backup

1. Open Settings → Backup & Restore → Portable Backup. To carry your saved secrets too, tick Include my saved credentials first (off by default — see Carrying your saved credentials); then click Export a backup….
2. Choose where to save the .amcbackup file.
3. Omniscio shows the file's recovery code exactly once, in a "Backup Created" dialog. Save this code somewhere safe right now (a password manager is ideal) — it is not shown again and is not stored anywhere in Omniscio. Tick "I've saved this" to confirm. On the same machine that made the export, you generally won't be asked for the code again (see below) — but on any other machine, or if this machine's credential store is unavailable, the code is the only way back into that file.
4. Optionally click "Show in folder" to reveal the saved file.

Import a backup

1. Open Settings → Backup & Restore → Portable Backup and click Import a backup…, then pick the .amcbackup file (or copy the file onto the new machine first, e.g. via USB or a cloud drive, and pick it from there).
2. If the file needs its recovery code (a different machine, or no matching device key), Omniscio asks for it. Enter the code you saved at export time.
3. Omniscio shows a preview: when the backup was made, the app version it came from, and how many projects/sessions/messages/attachments it contains. Nothing has changed yet.
4. Confirm to apply. What happens next depends on the destination machine:
   • Brand-new / empty install → full restore. Omniscio takes an automatic safety snapshot first, stages the restore, and asks you to restart — the restore completes on the next launch. If the backup included credentials, they are re-sealed under this machine's secure storage while the restore is staged, so your accounts and API keys work straight away after the restart (no re-login).
   • Install that already has data → additive merge, no restart needed. Omniscio takes the same automatic safety snapshot first, then adds everything from the backup that isn't already present: new projects and sessions with their conversation history, plus other user content (tags, bookmarks, saved prompts, automations, and more). Your existing local data is never overwritten or deleted — only new rows are added. Non-secret settings you haven't set locally are also copied over. If the backup included credentials, Omniscio restores the machine-independent ones (API keys, provider tokens) live — re-sealed under this machine's secure storage, and only where you don't already have a value, so a newer local secret is never clobbered. Per-account sign-ins can't be matched across installs (each machine mints its own account IDs), so those still go through the credential-recheck wizard.

On a fresh install with no projects yet, and once you're signed in, Omniscio may show a one-time banner — "Have a backup from another computer? Import it now." — as a shortcut straight into this flow. Dismissing it is permanent for that install.

Do both computers need the same version of Omniscio?

No. The two machines can be on different versions — which is the normal case, since the whole point is carrying your data to a computer you set up at a different time. Omniscio matches your information up by name rather than by position, so a backup made by an older or a newer version still imports.

Two things follow from that, and Omniscio tells you about both:

• Importing a NEWER backup into an older Omniscio — anything the newer version stores that this one doesn't understand yet can't come across. Everything else imports, and you get a message saying some details were left out. Updating this computer and importing again brings the rest.
• Importing an OLDER backup — nothing is lost. Fields added since the backup was made simply start at their normal defaults, exactly as they would for anything you created before that update.

Omniscio still refuses an import it genuinely can't complete — a backup missing something this version requires, or one from a version so old its data is shaped differently. In that case it says so and asks you to put both computers on the same version first.

One limit sits in the file itself rather than in your data: a backup written by a version that compresses its backups (see "What's inside the file, and how it's protected" below) cannot be opened by a version from before compression was added. Update that computer first; backups made before compression was added still open on newer versions.

Earlier behaviour (fixed 2026-08-31): any version difference at all blocked the import, and the message suggested using "Replace mode" — a button that exists for Backup Mirror but not here, so there was nothing to switch to.

What's inside the file, and how it's protected

• Format: a single .amcbackup file — a short plaintext header (a fixed 6-byte marker, a format-version byte, and a length-prefixed JSON manifest) followed by one encrypted block. The manifest itself has no secrets in it — it only lists which "unlock methods" (see below) exist for the file, each already encrypted.
• Encryption: the encrypted block is your whole mirror bundle (database + config + attachments), compressed as a whole and then sealed under a freshly generated random key (AES-256-GCM, the same authenticated encryption used elsewhere in Omniscio) — any tampering with the file is detected and rejected, never silently restored as garbage.
• Size: the bundle is compressed (zstd) before it is encrypted, because encrypted bytes cannot be compressed. A backup of a database-heavy workspace is therefore much smaller than the data it holds. Backups exported before compression was added still import, but a version from before compression cannot open a compressed backup — update that computer first.
• Unlock methods ("slots"): that random key is never handed to you directly. Instead it's wrapped so it can be recovered two ways:
  • Recovery code — always present. A fresh, random, 32-character code (grouped in dashes, e.g. ABCD-EFGH-1234-JKMN-...) that only you see, shown once at export time. This is the one that matters when you're moving the file to a different computer.
  • This computer's device key — present only when this machine's OS credential store is available. It lets Omniscio unlock a backup you made on this same machine without re-typing the recovery code (handy if you re-import your own recent export as a quick local check).
• Never overwrites without asking, never loses your current data on import — a mandatory safety backup is taken immediately before any import is applied, whichever mode is chosen.

Carrying your saved credentials (opt-in)

By default a Portable Backup carries no credentials — Omniscio seals your secrets (API keys, OAuth tokens, sign-in tokens) to the OS keyring, which is bound to this machine, so a normal export strips them and you sign back in on the new computer. That machine-binding is also why an OS reinstall or machine change would otherwise silently wipe every saved secret.

Ticking Include my saved credentials before you export closes that gap:

• What it does — while your secrets are still readable on the source machine, Omniscio captures them into the backup's already-encrypted payload (never a separate or plaintext file), root-independently. On import it re-seals each one under the new machine's keyring: live for a merge, or into the staged config for a full restore, so nothing is ever written to disk in the clear.
• Off by default, per-export — the checkbox starts off and resets after each export, so a credential-bearing backup is always a deliberate choice. The import preview warns you when a file carries credentials.
• The trade-off you're accepting — a credential-bearing backup plus its recovery code together grant access to those secrets on any machine. That is the deliberate cost of not losing them; store the file and its code safely.
• Fails safe — if the new machine's keyring is unavailable at import time, Omniscio refuses to restore the credentials rather than write them unencrypted; the rest of the import is unaffected and you re-enter the secrets by hand once the keyring is back.
• Scope (v1) — the secrets kept in config.json (provider API keys, account tokens, the openclaw token, and the encrypt-at-rest settings). Secrets stored in the database (MCP / cron env, the automation vault) are a later phase.

Cloud backup (the second, off-machine copy)

Beside the local .amcbackup file, Portable Backup has a cloud arm: the same encrypted archive can be stored on Omniscio Cloud, tied to your account, so you keep an off-machine recovery copy without carrying a file between machines. It sits on the same Settings card, under Omniscio Cloud backup, and is available on the plans that include cloud backup.

It is a second, independent copy, not a sync of the local file. The .amcbackup file you exported and the cloud copy are separate objects, each uploaded, restored and deleted on its own — deleting one leaves the other exactly as it was.

• Upload seals the same full-mirror archive and stores it in your own cloud slot, returning the same one-time recovery code the local export does. It never touches your local data, so it applies immediately. The archive is end-to-end encrypted — Omniscio can never read it, and your recovery code is still required to restore it on another machine.
• Restore brings the cloud copy back onto this machine through the same apply path as importing a local .amcbackup file: a full restore that replaces local data on an empty install, an additive merge (existing rows always win) on a populated one, and a mandatory pre-import safety snapshot either way. It is not a read-only download — see Import a backup for how the mode is chosen.
• Delete removes the cloud copy permanently. There is no undo and no trash folder. Local data is untouched, but the off-machine recovery point is gone — if that copy was the only backup you kept away from this computer, you have no recovery path left until you upload a new one.

An AI session can ask for any of the three. The cloud routes are on the CLI — POST /portable-backup/cloud-export, POST /portable-backup/cloud-restore, and DELETE /portable-backup/cloud-backup. Export applies immediately, exactly like the local export. Restore and delete are always approval-gated in Omniscio's approval inbox and cannot be toggled off, and both require the full CLI token rather than a scoped agent-session token — so an agent can request a full-install overwrite or a wipe of your recovery copy, but it can never approve either one for itself.

Scope and limits

• The recovery code is shown exactly once and never stored — if you lose it and don't have the original device's device-key available, that backup file can't be opened. Treat it like a one-time password: write it down, put it in a password manager, and don't rely on Omniscio to remind you later.
• Merge mode is additive-only — it never deletes or overwrites anything already on the destination machine, and it never overwrites the mode choice: Omniscio decides full-restore vs. merge automatically from whether the destination has data, there is no manual override.
• Credentials travel only when you opt in — a normal export strips every secret (you sign back in on the new machine). Ticking Include my saved credentials re-wraps them into the encrypted backup and restores them under the new machine's keyring on import; see Carrying your saved credentials for the trade-off, the fail-safe, and the v1 scope.
• CLI: POST /portable-backup/export (creates a new archive immediately, requires the CLI's normal auth; optional JSON body { includeCredentials: true } opts into the credential re-wrap) and POST /portable-backup/import (always requires human approval in Omniscio's approval inbox before it applies — an AI agent can never approve importing another machine's data into this one by itself). In the approval card and its technical-details view, the recovery code is always shown masked. The cloud arm adds three more: POST /portable-backup/cloud-export (immediate, like the local export), plus POST /portable-backup/cloud-restore and DELETE /portable-backup/cloud-backup, which are always approval-gated and full-CLI-token-only — an AI session can request a full-install overwrite or a permanent wipe of the off-machine copy, but can never approve either for itself.

For agents

• Full technical contract (invariants + the tests that lock them): portable-backup-contract.md; the opt-in credential re-wrap has its own portable-backup-credentials-contract.md.
• Credential re-wrap (build/apply/reseal the credential bag, Main-only): src/main/services/backup/portable-backup-credentials.ts (buildCredentialBag / applyCredentialBag / resealCredentialBagIntoStagedConfig / parseCredentialBag). Export threads { includeCredentials }; import wires both modes.
• File format: src/main/services/backup/portable-backup-format.ts.
• Stream envelope and compression (shared with Backup Mirror): src/main/services/backup/mirror-stream-crypto.ts.
• Encryption + recovery code: src/main/services/backup/portable-backup-crypto.ts, src/main/services/backup/recovery-code.ts, src/main/services/backup/portable-backup-unlock.ts.
• Export/import orchestration: src/main/services/backup/portable-backup-create.ts, src/main/services/backup/portable-backup-import.ts.
• All-table merge classification: src/main/services/backup/all-table-merge.ts.
• Settings UI: src/renderer/src/features/settings/sections/data-transfer/DataTransferSettings.tsx.
• IPC channels: PORTABLE_BACKUP_EXPORT, PORTABLE_BACKUP_IMPORT_PICK, PORTABLE_BACKUP_IMPORT_PREVIEW, PORTABLE_BACKUP_IMPORT_APPLY.
• CLI routes: src/main/services/cli/cli-server-portable-backup-routes.ts.

Related

backup-mirror.md is the continuous encrypted mirror to a shared cloud-sync folder — no file to carry, but it needs setup on both ends. setup-backup.md is the weekly encrypted config-only backup emailed to your Gmail, carrying no chats. data-transfer.md is the manual, unencrypted, full-replace-only export/import ZIP. And post-restore-credential-wizard.md covers the wizard that runs after a restore brings in credentials that can't be decrypted on the new machine.