--- title: Portable Backup (one-file encrypted export/import) --- # 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](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](setup-backup.md) > emails a small, config-only bundle weekly (no chats). [data-transfer.md](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**. It is currently an **in-development ("Lab") feature** — hidden by default. Turn it on at **Settings → Lab → Portable Backup** (setting `portableBackupEnabled`, env var `AMC_SHOW_PORTABLE_BACKUP`). ## 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](#carrying-your-saved-credentials-opt-in)); 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](#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](#carrying-your-saved-credentials-opt-in) 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](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](setup-backup.md) is the weekly encrypted config-only backup emailed to your Gmail, carrying no chats. [data-transfer.md](data-transfer.md) is the manual, unencrypted, full-replace-only export/import ZIP. And [post-restore-credential-wizard.md](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.