--- title: Machine Migration (moving Omniscio to a new computer) --- # 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](#no-mirror-use-exportimport-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](#beyond-amc--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](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 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](https://github.com/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](https://github.com/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 ` | 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](https://github.com/openclaw/gogcli), build with Go, and place the resulting `gog.exe` in `~/.local/bin/` 2. **Re-authenticate** — run `gog auth add ` 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 ""` | | `~/.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\\...` won't match if the new machine uses `C:\Users\\...` - **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 ""` 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 ` (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](post-restore-credential-wizard.md) — the auto-detection wizard that guides you through re-entering broken credentials after a cross-machine restore - [Backup Mirror](backup-mirror.md) — full technical details (encryption, storage layout, IPC channels, settings keys) - [Setup Backup to Gmail](setup-backup.md) — lighter configuration-only backup via email - [Export / import all data](data-transfer.md) — manual full export/import as ZIP - [Database migrations](database-migrations.md) — how schema upgrades work (relevant to cross-version restores) - [Is my data encrypted?](is-my-data-encrypted.md) — encryption map across all Omniscio surfaces