Omniscio

Portable Backup (one-file encrypted export/import)

A one-file encrypted backup you carry between computers yourself: what the .amcbackup file holds and how it is protected, how export and import work, how Omniscio picks a full restore or an additive merge, and how the optional credential re-wrap lets your saved secrets travel with it. An additive merge carries your personal-development content too — coaching artifacts, goals and their check-ins, bookmarks, the coach's summary of each conversation segment, the facts it extracted about you, your core profile, the insights drawn across your artifacts, the context you pinned, the feedback you wrote about a session, and your journal entries and Life Inventory takes — so a second computer shows the same coaching and journal history instead of only the artifact list. A journal entry that arrived in an older backup's non-UTC timestamp format is normalised to UTC on the way in, so it keeps the day it was written on.

On this page

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 or deleted, except mind maps, where the newer copy wins) 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 — except mind maps, where the newer copy wins (see Merge mode below). 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.

A record with a missing or oddly-formatted date

Some records must always carry a date — a meeting folder, for instance. If a backup holds one of those with the date missing (or written in an old style), Omniscio fills it in from the record's other date, or from the moment of the import when there is nothing else to use, and then brings the record across. The point is that one such record can no longer stop the rest of the import: everything else still comes across.

You are told how many items had a date or time Omniscio could not read. That count gets its own line, separate from "Couldn't restore N items", because the two describe different losses: an unreadable date does not drop its record — the record arrives with that one field blank (or filled in from the moment of the import where the field is required), so saying the item was "left out" would overstate what you lost. The sentence says plainly that the items came across, but without that value.

The same applies to dates stored in older styles. A plain date (2026-07-12) or a date and time without a time zone is read as UTC rather than as your computer's local time, so the same backup imports to the same dates whichever machine or time zone it is restored on.

Tasks that belong to a different sign-in

Every Tasks row (tasks, projects, check-ins, day log, learnings, planning profile, plan chat) is filed under the Omniscio sign-in that owns it, and Tasks only shows rows filed under the account that is signed in now. A merge copies that owner as written in the backup. So if a backup was made under a different sign-in than the one you use now (a replacement computer where you signed in and got a different account id, or an account that was deleted and re-created), its Tasks rows come across but stay hidden from Tasks.

The import cannot fix that, but it no longer reports a clean success. It counts the Tasks rows the merge added that are filed under another sign-in and adds its own line to the import warnings: "N Tasks items from the backup belong to a different Omniscio sign-in than the one you're using now, so they won't show up in Tasks here." The count is only rows this import added, so a computer that already holds two accounts' Tasks does not warn on every import. Moving those rows to the current account (a re-key) does not exist yet; it waits on the team confirming whether one person can ever receive a new account id.

Sessions another of your computers owns

With Cross-Device Sync on, a session started on another of your computers can only be changed by that computer, and this one keeps a read-only copy. A merge used to try to add the backup's newer messages into those copies too; the protection refused, and the whole import rolled back with nothing merged.

A merge now leaves those sessions alone and imports everything else. It counts what it left out and adds a line to the import warnings naming the count and up to five of the sessions: "N messages from the backup weren't merged into these sessions: “Planning” (3), … A session started on another of your computers can only be changed on that computer." To bring that history here, open the session, choose Continue on this computer, then import the backup again. The same line appears after a Backup Mirror restore from a file; the unattended Sync now pull keeps it to the app's log.

A merge never undoes a deleted or edited task

A merge adds only rows this computer does not already have, matched by id. A task that was deleted here, or edited here, since the backup was made still exists here, so the backup's copy is ignored and the task stays deleted or edited. This is why merging an older backup cannot bring back tasks that were deleted or overwritten.

The import now says so. It counts the backup's tasks that differ from the copy already here (deleted here but alive in the backup, or with different text) and adds a line to the import warnings: "N tasks in this backup differ from the copies already on this computer. The copies here were kept, because restoring a backup this way never undoes a deletion or an edit." The same line appears after a Backup Mirror restore from a file. The unattended Sync now pull stays quiet, because differing copies are normal when two computers both edit Tasks. To get deleted or overwritten tasks back, use a full restore of an older backup, which replaces everything on this computer; a restore of only the Tasks from a backup does not exist yet.

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.
  • In the CLI, credentials are owner-only — POST /portable-backup/export with { "includeCredentials": true } requires the machine-wide, full-trust CLI token (~/.amc/cli-token). A scoped, per-session agent token is refused with a 403: it may take a credential-free backup, but it may not walk away with your saved secrets.

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, mind maps aside) 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, and reports itself through GET /portable-backup/cloud-export/status when it outlives the request. 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 keeps both sides — it never deletes anything already on the destination machine (mind maps aside, see below), 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. A row the destination already has is normally left exactly as it is; the exception is your planning profile and Plan chat, which are one row per signed-in account rather than one per task. If you plan a day or send one Plan chat message on the new machine before importing, the merge combines them instead of discarding the backup's copy: the whole profile is taken from whichever machine saved that profile most recently, any field left blank there is filled in from the other copy, and the two chat threads are interleaved by time, keeping each question directly above its reply. A profile or thread that is still cleared on this machine is left alone, so clearing it is never undone by an import; one you cleared and then used again merges normally. A chat thread that cannot be read is left byte for byte as it is instead of being overwritten.
  • Mind maps are the other exception: the newer copy wins. For a map both machines have, the copy that was changed most recently replaces the other, with no copy of the replaced version kept, and a map deleted on the backup's machine after its last edit here is deleted here too. Export any map you want to keep as it is (Export → JSON) before importing. A newer copy that belongs to a different signed-in account is left as it is here, and the restore summary counts it among the items it could not restore. See Mind Map.
  • A row the app no longer accepts is repaired or skipped on its own — restoring never costs you the rest of the table. A task note or link whose task is no longer in the backup is skipped, and the import warns you how many rows it dropped; a restored task whose saved value has fallen outside what the app accepts today comes back with that one field blank instead of the whole tasks table being dropped.
  • 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 is honoured ONLY for the machine-wide CLI token — a scoped agent-session token is refused with a 403, since re-wrapping the user's saved secrets is an owner action on an otherwise agent-reachable route) 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.
  • A backup can take longer than a CLI request is allowed to run, so both export routes answer in two steps. Each holds the request open for up to 150 seconds and answers 202 { started: true, jobId, timedOut, statusPath } when the export is still going (or immediately, when the body says { "wait": false }). The one-time recovery code is minted and readable from that moment — before the database snapshot, the save dialog and the upload — so a slow export can never take the code down with it: GET /portable-backup/export/status and GET /portable-backup/cloud-export/status return the job for the caller that started it, as { state, recoveryCode, codeValid, … }. codeValid is false until the export reports done — hold the code when you read it early, tell the user it only once the export lands, and keep the previous code until then: while the job has not landed a backup of its own it also returns previousRecoveryCode, the code that still opens the backup currently in the cloud (or the last file written). A read that names no job of the caller's answers { "state": "idle" }. The cloud holds ONE backup per account whatever started the export, so a code whose backup a later export has replaced comes back as "codeValid": false, "supersededByNewerBackup": true — never hand a user a code on the strength of an old export.

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.

Last verified 2026-10-06