Machine Migration (moving Omniscio to a new computer)

What it is

How to move your entire Omniscio install — sessions, conversations, settings, attachments, automations — to a new machine. The recommended path is the Backup Mirror feature, which creates an encrypted full-state snapshot you can restore on the new computer in under a minute.

Where to find it

Backup and restore live under Settings → Backup, with the manual export and import beside them. The restore is what runs on the new computer; the snapshot itself is produced on the old one.

How it behaves

Which backup method should I use?

Omniscio has three backup/export paths. Pick the one that fits your situation:

Method	What it includes	Best for
Backup Mirror (recommended)	Everything — database, conversations, config, attachments	Moving to a new machine, disaster recovery, hard drive failure
Export all data (manual ZIP)	Everything except API keys/credentials	One-time transfer when you didn't set up a mirror beforehand
Setup Backup to Gmail	Configuration only — projects, snippets, settings (no chats)	Keeping your project list and settings backed up, not full migration

If you're reading this because you already have a new machine and didn't set up a mirror: skip to No mirror? Use Export/Import instead.

The recommended path: Backup Mirror

Step 1 — Set up the mirror (source machine)

1. Open Settings → Backup & Restore → Backup Mirror.
2. Pick a folder. Omniscio detects your cloud-sync folders (Dropbox / OneDrive / iCloud Drive / Google Drive) and offers each as a one-click chip that creates an Omniscio-mirror subfolder for you. Or click Browse… to choose one yourself (it opens pointed at your cloud folder). The sync client replicates the archives off-machine automatically.
3. Set a passphrase. Click Generate strong passphrase for a strong, typeable one you can re-type on the new machine (then copy it with one click), or type your own. Save it in your password manager and tick I've saved this passphrase — without it, the archives are unrecoverable (no recovery code or reset).
4. Set Retention (default 5 — keeps the 5 newest archives).
5. Toggle Enable backup mirror on. (The first time, Automatic sync defaults to When I open & close AMC, so once you set it up it keeps itself in step.)
6. Click Mirror now to create your first archive immediately.

A .amcmirror file appears in your chosen folder within seconds. Your cloud-sync client replicates it off-machine. From now on, every automatic backup also writes a fresh mirror.

Step 2 — Restore on the new machine

1. Install Omniscio on the new machine.
2. Make sure the cloud-sync folder is accessible (sign into Dropbox/OneDrive/iCloud, or copy the .amcmirror file over manually via USB/network).
3. Open Settings → Backup & Restore → Backup Mirror.
4. Click Pick folder and point it at the same cloud-sync folder (or wherever you placed the .amcmirror file).
5. Your archives appear in the list, newest first.
6. Type the same passphrase you used on the source machine.
7. Click Replace (recommended for migration — replaces the fresh empty install with your full backup).
8. Omniscio stages the restore and asks you to restart.
9. Restart Omniscio. On launch, it swaps in your database, config, and attachments.
10. If you restored onto a different machine, the Post-Restore Credential Wizard opens automatically — it scans all credential stores and external tools, then shows you exactly which items need re-entering. Walk through the wizard before starting your first session.
11. Done — your sessions, conversations, settings, automations, and attachments are all back.

What migrates

• All sessions and full conversation history
• All attachments (images, PDFs, docs)
• Projects, bookmarks, and snippets
• Automations, recipes, and cron jobs
• Settings and preferences
• Account records (but see below about credentials)
• Cold-storage archive database (if present)
• Claude Code global CLAUDE.md (~/.claude/CLAUDE.md, if present)
• Claude Code per-project CLAUDE.md files (~/.claude/projects/*/CLAUDE.md, if present)
• Claude Code auto-memory files (~/.claude/projects/*/memory/, if present)
• User-authored Claude Code skills (~/.claude/skills/, if present)
• Global Claude config — ~/.claude/settings.json, keybindings.json, and scripts/ (if present)
• File-based recipe definitions (~/.claude/recipes/*.recipe.json, if present)
• Per-project notes (the free-text notes you write per project)

What doesn't migrate (and why)

• API keys and OAuth tokens — stored with OS-level encryption (safeStorage), which is bound to the source machine's keychain. After restoring, re-enter your API keys at Settings → Accounts and re-authenticate any OAuth connections. This is a security feature, not a bug.
• Running CLI sessions — Claude CLI processes are pinned to the source machine. Restored sessions have their CLI link cleared and use transcript injection to resume cleanly on first spawn. Omniscio handles this automatically — open a session and send a message.
• Log files — diagnostic-only, not included in the archive.
• Screen recordings & screenshots — the recording/screenshot media files live on the source machine and aren't carried in the backup, so those library entries can't travel with it. After a cross-machine Replace restore, Omniscio automatically hides the recording entries whose media file is absent, so you don't see un-openable items in your library (a same-machine restore keeps its files, so nothing is hidden there).
• External tools, drive mappings, and CLI credentials — Omniscio's backup covers Omniscio's own data, but your broader development environment (drive letters, installed CLIs, tool-specific auth, SSH keys, Claude Code settings) is machine-specific. See Beyond Omniscio — your development environment for the full checklist.

Replace vs Merge — when to use each

Replace — "Give me back my whole Omniscio."

• Overwrites the current database, config, and attachments with the archive contents
• Creates a pre-restore safety snapshot first (you can revert via file manager if needed)
• Requires a restart to complete
• Use for: migration to a new/fresh machine, disaster recovery, hard drive replacement

Merge — "Add another machine's chats (and their projects) without losing what I have here."

• Inserts sessions and messages that don't already exist locally, plus the projects those sessions belong to (and any other active projects that machine has)
• Only adds — your existing local sessions and projects are never overwritten
• No restart needed — applied immediately
• Requires the archive and local database to be on the exact same schema version
• Use for: pulling session history from a second machine, combining work from two installs

No mirror? Use Export/Import instead

If you didn't set up a mirror before the migration:

1. On the source machine, go to Settings → Backup & Restore → Export all data.
2. Click Export — Omniscio creates a ZIP file with your full database, settings, and attachments (unencrypted — handle with care).
3. Copy the ZIP to the new machine (USB, network share, cloud drive).
4. On the new machine, go to Settings → Backup & Restore → Import data.
5. Select the ZIP file. Omniscio shows a preview of what's inside.
6. Click Import — this replaces the current install and restarts.

See data-transfer.md for full details.

After the migration, set up Backup Mirror so you're covered next time — follow Step 1 above.

Troubleshooting

"Wrong passphrase or tampered file"

The passphrase doesn't match the one used to create the archive. Check your password manager. There is no recovery — the archive uses AES-256-GCM, and a wrong passphrase means decryption fails completely.

"Schema version mismatch" (merge mode only)

The archive was created on a different Omniscio version than your current install. Update both machines to the same version and try again, or use Replace mode instead (replace handles cross-version restores because Omniscio's startup migrations upgrade the database automatically).

Sessions show as "needs attention" after restore

Normal. Restored sessions need to re-establish their CLI connection. Open a session and send a message — Omniscio injects the conversation transcript into a fresh CLI session automatically.

Credentials missing after restore

Expected. On a cross-machine restore, the Post-Restore Credential Wizard opens automatically and shows you every credential that needs re-entry — Omniscio accounts, provider API keys (including each saved GLM / z.ai account key), MCP server secrets, cron job env vars, integration tokens, and more. It also flags your SSH remotes whose keys or host-key pins (known_hosts) didn't survive the move. Walk through the wizard to fix everything in one pass instead of discovering failures one at a time. You can reopen it later from Settings → Backup & Restore → "Run credential check…".

Cron jobs broken after migration

Cron job definitions migrate with the database, but several things about them are machine-specific and need manual attention after restoring on a new computer. Test every active cron job after migration — go to Settings → Cron and trigger a manual run for each one.

Common failures and how to fix them:

Symptom	Cause	Fix
spawn node ENOENT or spawn <path> ENOENT	Script path, executable path, or working directory points to a location that doesn't exist on the new machine	Edit the cron job and update all paths to match where the project lives on this machine
MODULE_NOT_FOUND (e.g. tsx, ts-node)	Project was re-cloned but node_modules weren't installed	Run npm install (or pnpm install) in the project directory
Missing required environment variable	Cron job env vars were encrypted with the old machine's OS-level encryption (DPAPI on Windows, Keychain on macOS) and can't be decrypted here	Re-enter the env vars on the cron job — edit it and set each variable again
Could not load the default credentials (Google/Firebase)	Google Cloud Application Default Credentials are machine-specific	Run gcloud auth application-default login and sign in with the relevant Google account
Job runs but produces wrong results	Paths inside the script itself may reference old-machine locations	Check the script source for hardcoded paths and update them

Checklist — run through this for every active cron job after migration:

1. Open the cron job and verify script path, working directory, and executable path all exist on the new machine
2. If the job uses env vars, re-enter them (they won't decrypt from the old machine)
3. If the project uses Node.js dependencies, run npm install in the project directory
4. If the project uses Google Cloud / Firebase, run gcloud auth application-default login
5. Trigger a manual test run and confirm it succeeds
6. Check any other machine-specific credentials the script depends on (service account files, SSH keys, local config files)

"I already started using the new machine and now I want my old sessions too"

Use Merge mode instead of Replace. It adds the archive's sessions and their projects without overwriting your existing work. Both machines must be on the same Omniscio version.

File picker doesn't show .amcmirror files

Fixed (July 2026). The Backup Mirror restore paths show your .amcmirror archives correctly: Restore from mirror lists them straight from the configured folder, and Restore from file opens an OS picker filtered for Omniscio Mirror (.amcmirror) with an all-files fallback. (The separate Import data flow is for the unencrypted export ZIP — use the Backup Mirror section, not Import, to restore a mirror.)

Source machine is dead / inaccessible

If your cloud-sync folder has a copy of the .amcmirror file, you can restore from that. If not and you have no export ZIP, the data is unrecoverable — this is why setting up Backup Mirror proactively is important.

Beyond Omniscio — your development environment

The Backup Mirror restores everything inside Omniscio, but Omniscio sits on top of a broader development environment that is machine-specific. After restoring your Omniscio data, walk through the checklist below to get the rest of your environment working.

Dev Drives and drive letter mappings

Omniscio may be configured to create worktrees on a dedicated drive (e.g. L:\AMC-Worktrees on a separate NVMe Dev Drive). Drive letter assignments do not transfer between machines — the new machine needs the same drive set up, or the path updated.

After migration:

1. Check if your worktree drive exists on the new machine. If not, either:
   • Format and assign the same drive letter to the new disk (Windows Settings → Disk Management), or
   • Write the new path into worktree-locations.local.json at the repo root — a git-ignored, per-machine override that wins over the committed worktree-locations.json, so your drive letter is never committed. Set createIn to a valid path on the new machine and add it to scanContainers. Do NOT edit the committed worktree-locations.json: that is the repo's shared default, and a machine path there reaches every teammate. Where the app is running, the same choice is available in the UI under Edit Project → More options → Worktree location, which writes that override for you.
2. If you used Windows subst commands to create virtual drive mappings, recreate them — these are not persisted across machines

External CLI tools (toolchain)

Omniscio integrates with external command-line tools that are installed separately. None of these transfer with the backup — they must be reinstalled on the new machine.

Check what's missing: Open Settings → Connected Tools. Tools that Omniscio can detect will show their status (installed or missing). Most can be reinstalled directly from the Toolchain screen.

Auto-installable tools (Omniscio can install these for you via Settings → Connected Tools):

Tool	Install method	Notes
Claude Code CLI	npm
Git	winget
GitHub CLI	winget	Needs gh auth login after install
Google Cloud SDK	winget	Needs gcloud auth application-default login after install
Google Workspace CLI (gws)	winget	Needs gws auth login after install
Tailscale	winget
pnpm	npm
Playwright	npm
Repomix	npm
FFmpeg	winget	Required for audio/video conversion
yt-dlp	winget	Required for media downloads

Manual-install tools (Omniscio cannot auto-install these):

Tool	How to install	Notes
gog (gogcli)	Build from source (openclaw/gogcli), place binary in ~/.local/bin/	See the gogcli section below — requires new OAuth credentials
browser-use	pip install browser-use	Python-based
RTK	Windows: put rtk.exe from the rtk-ai/rtk releases on your PATH; macOS/Linux: brew install rtk	Token-saving wrapper for dev commands

Your own CLIs (anything you built or installed yourself that is not listed above): reinstall them on the new machine. Once one is on your PATH, the Tools view lists it under Installed after you click Scan now at the top of its list.

Re-authentication checklist

Many tools store their own credentials on the machine. After migration, you need to re-authenticate each one. None of these credentials transfer — they are bound to the source machine's OS-level encryption or stored in tool-specific locations.

Tool / Service	Re-auth command or action	What happens if you skip it
Omniscio API keys	Settings → Accounts → re-enter each key	Sessions can't start; AI features broken
Omniscio OAuth connections	Settings → Accounts → re-authenticate	OAuth-dependent features fail
GitHub CLI	gh auth login (device code flow)	Git push/PR operations fail
Google Cloud SDK	gcloud auth application-default login	Firebase/GCP cron jobs fail
Google Workspace CLI (gws)	gws auth login	Google Workspace integration fails
gogcli	gog auth add <your-email>	Google Docs/Sheets/Gmail via gog backend fails
MCP server secrets	Settings → MCP Servers → re-enter secrets for each custom server	Custom MCP tools unavailable
Cron job env vars	Settings → Cron → edit each job → re-enter variables	Cron jobs fail with "missing env var"
SSH remotes	Settings → SSH Remotes → regenerate keys → re-deploy public keys to remote servers	SSH remote sessions fail to connect

gogcli — special handling required

The gog CLI (gogcli) requires extra attention because its OAuth credentials cannot be copied from the old machine. Google Cloud Console only lets you download a client secret JSON file once — if you didn't save it, you need to generate a new one.

Steps to restore gogcli on the new machine:

1. Rebuild the binary — clone openclaw/gogcli, build with Go, and place the resulting gog.exe in ~/.local/bin/
2. Re-authenticate — run gog auth add <you@example.com> and complete the browser sign-in flow. This authenticates against gogcli's own Google Cloud project (separate from Omniscio's OAuth)
3. Verify — run gog me --json to confirm your identity, then test with gog gmail labels or gog docs list

If gog is broken but you need Google features immediately, Omniscio has a native Google API fallback (googleapis npm package) that handles Gmail, Docs, Sheets, Calendar, and Drive without requiring gog. The fallback activates automatically when gog is unavailable — you may not notice gog is missing until you try a gog-specific feature.

Cloud test fleet cache

If you use the cloud test offload system (--cloud flag on test/typecheck/lint/build), the fleet cache at ~/.amc/cloud-fleet.json does not transfer with the backup. This file tells Omniscio which Google Cloud VMs are available to run tests on. Without it, the system falls back to a hardcoded default pool that may list VMs that have been deleted — causing intermittent "test ran locally" alerts when a session randomly picks a dead VM.

After migration:

1. Run npm run cloud:sync-fleet to rebuild the fleet cache from what actually exists in GCP
2. Verify with npm run cloud:status or npm run cloud:dashboard that the expected VMs appear

If you don't use cloud test offload, skip this — it only applies to development environments with GCP runners provisioned.

Claude Code files that don't transfer

The Backup Mirror includes your CLAUDE.md files, auto-memory trees, user-authored skills (~/.claude/skills/), your global config (settings.json, keybindings.json, scripts/), and your file-based recipes (~/.claude/recipes/), but several machine-bound Claude Code files are not included:

File / Directory	What it is	Post-migration action
~/.claude/.credentials.json	Claude Code's own auth credentials	Omniscio injects credentials at session spawn — no action needed unless you use Claude Code standalone
~/.claude/amc-repo.path	Pointer telling scripts where the Omniscio repo lives on this machine	Run bash ~/.claude/scripts/set-amc-repo.sh "<path-to-repo>"
~/.claude/secrets/	DPAPI-encrypted secrets vault	Machine-bound; re-enter any secrets you stored

Tip: The Backup Mirror now carries your whole portable global ~/.claude/ setup — skills (~/.claude/skills/), global config (settings.json, keybindings.json, scripts/), and file-based recipes (~/.claude/recipes/) — so a single mirror restore brings all of them back; you no longer need the Gmail backup as well just to recover them. One thing to know: settings.json holds executable hooks and both it and scripts/ can contain machine-specific paths, so review them after a cross-machine restore. The only ~/.claude/ items that never travel are the deliberately machine-bound ones (secrets/, .credentials.json, amc-repo.path) — see the table above.

Memory files with machine-specific paths

Global Claude Code memory files (~/.claude/projects/*/memory/) do transfer via Backup Mirror — they're included alongside CLAUDE.md files and auto-memory trees. However, these files may contain hardcoded paths from the old machine that become stale after migration:

• Username changes — paths like C:\Users\<old-name>\... won't match if the new machine uses C:\Users\<new-name>\...
• Drive letter changes — references to L:\AMC-Worktrees or other mapped drives
• Binary locations — CLI tool paths documented in reference files (e.g., reference_cli_inventory.md)

After migration, review any reference-type memory files that document file paths, CLI locations, or machine-specific configuration. Update stale paths to match the new machine. Sessions that rely on these files for CLI access or tool locations will silently get wrong information until the paths are corrected.

Per-project .claude/ configs (no action needed)

Each project directory has .claude/settings.json and .claude/amc-instructions.md files that Omniscio uses to configure Claude Code sessions. These may appear missing after migration if the project hasn't been opened yet — this is normal. Omniscio automatically regenerates these files on every session spawn via injectDefaultAgentInstructions(), so they self-heal the first time you open a session in that project. No manual action is needed.

Post-migration environment checklist

The Post-Restore Credential Wizard covers most of these items automatically — it detects broken credentials and missing paths and gives you fix-action buttons for each. The checklist below is for reference or if you dismissed the wizard early:

• Drive letters — verify your worktree drive exists (e.g. L:\); if the path changed, update worktree-locations.local.json (the git-ignored per-machine override), never the committed worktree-locations.json
• Repo pointer — run bash ~/.claude/scripts/set-amc-repo.sh "<path>" to set ~/.claude/amc-repo.path
• Omniscio credentials — re-enter API keys and re-authenticate OAuth at Settings → Accounts
• Toolchain — open Settings → Connected Tools, install missing tools
• GitHub CLI — run gh auth login
• Google Cloud — run gcloud auth application-default login (if you use Firebase/GCP features)
• gogcli — rebuild binary, run gog auth add <email> (if you use the gog Google backend)
• MCP servers — re-enter secrets for custom MCP servers at Settings → MCP Servers
• SSH remotes — regenerate keys and re-deploy public keys to remote servers
• Cron jobs — edit each active cron job, re-enter env vars, verify paths, trigger a test run
• Claude Code global config — settings.json, keybindings.json, and scripts/ now transfer via Backup Mirror; after a cross-machine restore, review settings.json hooks and any machine-specific paths in your scripts
• Cloud test fleet — run npm run cloud:sync-fleet to rebuild the fleet cache (if you use --cloud test offload)
• Private CLIs — re-clone and rebuild any private-repo CLIs you use
• Node.js dependencies — run npm install / pnpm install in any project directories you plan to work in
• Memory files with paths — review ~/.claude/projects/*/memory/ for reference files containing old-machine paths (usernames, drive letters, CLI locations) and update them
• Per-project .claude/ configs — no action needed; these auto-regenerate on first session spawn in each project

Setting up for next time

After any migration, immediately configure Backup Mirror on the new machine:

1. Settings → Backup & Restore → Backup Mirror
2. Pick a cloud-synced folder
3. Set a passphrase (save in password manager)
4. Toggle on and click Mirror now

Related

• Post-Restore Credential Wizard — the auto-detection wizard that guides you through re-entering broken credentials after a cross-machine restore
• Backup Mirror — full technical details (encryption, storage layout, IPC channels, settings keys)
• Setup Backup to Gmail — lighter configuration-only backup via email
• Export / import all data — manual full export/import as ZIP
• Database migrations — how schema upgrades work (relevant to cross-version restores)
• Is my data encrypted? — encryption map across all Omniscio surfaces