Omniscio

Setup Backup to Gmail

Weekly encrypted backup of your Omniscio configuration (not your conversations) emailed to your own Gmail inbox, with a one-click restore that pulls a bundle back out of email.

On this page

What it is

Weekly encrypted backup of your Omniscio configuration (not your conversations) emailed to your own Gmail inbox, with a one-click restore that pulls a bundle back out of email.

Omniscio builds a small ZIP every seven days holding everything you'd need to rebuild your Omniscio setup on a fresh machine — the row data from 18 SQLite tables (projects, bookmarks, snippets, automations, recipes' metadata, away-mode rules, etc.), your non-secret app settings, your ~/.claude/recipes/ files, and any user skill folders under ~/.claude/skills/. The ZIP is encrypted with a passphrase only you know, then sent as an attachment to your own primary Gmail address with the label AMC Backup.

The point is recovery, not history: if your laptop dies, your config.json is corrupted, or you want to mirror your Omniscio layout onto a second machine, the most recent email in AMC Backup plus your passphrase get you back to a working state in one round-trip.

It is not a chat backup. The bundle never contains your conversation messages, session transcripts, attachments, the SQLite database file itself, your Claude OAuth tokens, your API keys, or any other secret that lives in config.json. See What gets backed up below for the full inclusion list and the deliberate exclusions.

Because the database file is never in the bundle, turning this on does not give your data a copy that survives losing the machine, and it does not clear the "Backups are on the same disk as your data" warning. That warning clears only when the database itself is copied off this machine — a fully configured Backup Mirror, Cross-Device Sync, or an auto-backup folder on a different drive. Use Setup Backup alongside one of those, not instead of them.

What gets backed up

Included (per src/main/services/backup/setup-backup-service.ts SETUP_TABLES + the config/ and recipes/ and skills/ zones):

  • 18 SQLite tables (alphabetical): automations, away_mode_rules, bookmarks, cron_jobs, deploy_profile_entries, deploy_profiles, email_summarizer_rules, project_dividers, projects, prompt_sequences, quick_replies, recipe_schedules, rss_feeds, saved_prompts, spam_rules, tag_project_scopes, tags, webhook_sources. These are the tables that describe your setup — what projects you've added, what bookmarks you've saved, what snippets you've authored, etc.
  • Non-secret app settings from config.json — theme, keyboard shortcuts, sidebar order, feature toggles, and so on. Filtered through src/main/services/backup/setup-backup-service.ts, which deletes a denylist of known secret keys (OAuth tokens, API keys, setupBackupPassphrase itself, lastActiveProjectId, lastActiveSessionId). The separate recursive src/main/services/backup/setup-backup-service.ts walk — which nulls any string starting with enc: (the safeStorage-encrypted prefix used for credentials) — runs on the bundle's preferences payload (SSH remotes, muted projects, silence-until), not on the settings payload.
  • Recipe files — every .recipe.json under ~/.claude/recipes/ (your global recipes directory).
  • User skills — every folder under ~/.claude/skills/ containing a SKILL.md. Each skill is capped at 5 MB, and the skills zone at 15 MB in total. A skill that would exceed either cap is left out of the bundle — never truncated — and the build records a warning that the restore preview shows; the backup itself still completes and is emailed.

NOT included — these are deliberate exclusions, not bugs:

  • Conversation messages and session history. The sessions and conversation_messages tables are excluded entirely. A restored Omniscio has the same project/bookmark layout but starts fresh — your old chats stay on the old machine.
  • Attachments. Anything you've pasted, dragged, or paperclipped into a session.
  • The SQLite DB file itself. Omniscio reconstructs each table from JSON, not from a copy of mission-control.db. This keeps the bundle small and lets you restore across schema versions safely.
  • Claude OAuth tokens, API keys, refresh tokens, and any other safeStorage-encrypted credential. In the settings payload these are removed by the secret-key denylist; in the preferences payload any enc:... string is nulled by the recursive redaction walk. After a restore you re-sign in to Claude / Gmail / etc. once.
  • Your encryption passphrase. The passphrase is stripped from the bundle. It lives in your local config.json (safeStorage-encrypted with the enc: prefix — same protection Omniscio uses for OAuth tokens and API keys), but never travels to Gmail. Forget the passphrase and your encrypted bundles become unreadable; Omniscio has no recovery path. If you need a backup you can still open after losing the passphrase, use Portable Backup instead — it escrows a one-time recovery code that unlocks the archive on any machine even without the passphrase.

Where to find it

Open Settings → Backup & Restore → Setup Backup to Gmail (or type "setup backup" into the settings search bar). Restore lives in the same panel: point it at the .zip / .zip.enc file you downloaded from Gmail, type the passphrase, and choose Replace or Merge.

How it behaves

How to use it

  1. Open Settings → Backup & Restore → Setup Backup to Gmail (or just type "setup backup" into the settings search bar).
  2. Connect your Gmail account if you haven't already (the same one-click Google OAuth that powers Calendar / Drive / Sheets / Gmail integration).
  3. Toggle Enable setup backup on. The encryption field, the status card and Back up now only render once it is on — Restore from backup is always on the card, because restoring a bundle you already have never depends on the weekly send being switched on. Do not stop here: the send job is already running in the background and checks every hour, so once this is on and no backup is on record yet, the next check sends one — finish the next step in the same sitting.
  4. Set the Gmail backup passphrase — type it into the field and click Save. Stash it in your password manager. Without it the email is a plain, unencrypted ZIP — see the note below — and with it, a lost passphrase means the bundle is unrecoverable (there is no escrow and no recovery code).

The toggle first, then the passphrase — with no gap between them. Encryption is conditional on the field being non-empty: the scheduler checks it at send time and, when it is empty, emails the bundle as a plain, unencrypted ZIP — the passphrase ships blank by default and the toggle does not require one. Because the field only renders once the toggle is on, there is no way to set the passphrase first, so the safe habit is: turn the toggle on only when you are ready to type the passphrase immediately, and confirm the status card reads "Passphrase set" before you leave the panel. There is no grace period to rely on. The send job runs for the whole life of the app — it starts five minutes after launch and then checks every hour — and it skips a check once a backup attempt already sits within the last seven days. "Attempt" is the honest word: it covers a send, a deduped no-op (nothing changed since last week), and even a send that failed after the bundle was built — the weekly send is deliberately at-most-once, so a failed one is not retried until the week is up or you click Back up now. On a machine with no backup attempt yet — or one older than a week — the first check after you flip the toggle sends, and that check can land at any moment, including seconds later. The status card's Encryption row reads "Not encrypted" while no passphrase is stored and "Passphrase set" once one is.

  1. Click Back up now if you want to verify the round-trip end-to-end before trusting the schedule. The status card updates with Last backup: just now and the bundle lands in your AMC Backup Gmail label within a few seconds.

To restore, click Restore from backup in the same panel. A dialog opens, you point it at the .zip / .zip.enc file you just downloaded from Gmail, type the passphrase, and pick Replace or Merge mode. The dialog shows a preview (hostname, schema version, row counts) before you commit.

Omniscio stops every running session before it replaces the database, on whichever engine runs it — Claude's and every external engine's — because replacing the database underneath a live agent is how work gets lost. If any agent will not stop, the restore is refused before anything is replaced, with "Some agents did not stop, so nothing was changed. Stop them and try again." Stop those sessions by hand (see pause or stop a session) and restore again. A refused restore costs you a click; a restore taken under a live writer cannot be undone.

Encryption

The bundle is encrypted client-side, in the Omniscio main process, before it leaves your machine. The crypto is a portable AEAD with no OS keyring dependency, which is what lets restore work on a different computer.

  • Algorithm: AES-256-GCM (authenticated, so a wrong passphrase or any tampered byte fails decryption — you never get partial recovery).
  • KDF: PBKDF2 with SHA-256, 600,000 iterations (matches the OWASP 2023 minimum). Slow on purpose — typical key derivation takes a few hundred milliseconds, which is fine for a once-a-week backup but expensive enough to defeat brute-force on a leaked bundle.
  • Envelope layout (concatenated bytes, no magic header): [salt(16) | iv(12) | ciphertext(N) | authTag(16)]. Total overhead 44 bytes.
  • Salt and IV are random per backup, so two backups of identical data produce different ciphertexts — there's no oracle for "did your config change this week?".
  • Detection on restore: the file is a ZIP if its first four bytes are PK\x03\x04, otherwise it's treated as encrypted and decryptBundle() is run. So a plaintext .zip (a debug export) and an encrypted .zip.enc are both accepted — the restore dialog's file picker filters on zip / enc and reads whichever it is given.
  • Forward compatibility note. The on-disk envelope has no magic bytes or version field, so any future change to encryption parameters will be a flag-day migration — old bundles won't be distinguishable from new ones by inspection alone, and would need a new file extension or wrapper format to coexist.

Implementation: src/main/services/backup/setup-backup-crypto.ts.

Email delivery

Email delivery uses a small separately-installed Google Workspace CLI. Omniscio ships with two backends and you pick one at Settings → Gmail → Google CLI Backend:

  • gog (current default) — the openclaw/gogcli Go binary. Build from source per the openclaw/gogcli README, drop the resulting binary into ~/.local/bin/, and run gog auth add <you@example.com>. This is the backend backups use unless you switch, and only when it can actually serve the send — with no CLI installed, or a CLI that refuses before transmitting, the backup goes out through the account you connected with Connect Google instead, so a backup never dead-ends on a missing command-line tool.
  • gws (official, opt-in) — the official Google CLI at github.com/googleworkspace/cli. Install on Windows with winget install Google.WorkspaceCLI, on macOS/Linux with brew install googleworkspace-cli, or on any platform with npm install -g @googleworkspace/cli. Omniscio's Tools view also offers a one-click install. gws keeps its own Google credentials — it can't reuse gog's — so after install you must run gws auth login once before flipping the backend setting to gws.

Omniscio does not bundle either CLI; if the selected backend isn't on your PATH, the backup fails with a "command not found" error in the failure banner. Sending uses the same OAuth scope you already granted for that backend — no new permissions are requested.

  • Recipient: your primary Gmail address (resolved via gog me / gws gmail users getProfile, picking the entry flagged as both primary and sourcePrimary, with verified-email fallback).
  • Subject: Omniscio Setup Backup — <hostname> — YYYY-MM-DD.
  • Body: a short reminder that the bundle is encrypted and recovery requires your passphrase.
  • Attachment: setup-backup-<timestamp>.zip.enc when a passphrase encrypts it, setup-backup-<timestamp>.zip when none is set.
  • Label: AMC Backup (created on first send, then reapplied on every send so the inbox can be filtered down to backups easily).
  • Size cap: Gmail itself rejects attachments over 25 MB. Omniscio enforces a 20 MB cap on the plaintext ZIP before encryption (encryption adds only 44 bytes), so the email always fits with margin. If the finished ZIP would exceed 20 MB the backup fails with a failure card in the panel. The two skill caps behave differently: an oversized skill is skipped with a manifest warning rather than failing the backup (see Limits and non-goals).

Implementation: src/main/services/backup/setup-backup-mailer.ts.

Developer builds — no company Google client

A source checkout has no company Google OAuth client, and that is by design: src/main/services/google/google-oauth-client.ts resolves the client once at start from MAIN_VITE_GOOGLE_CLIENT_ID / MAIN_VITE_GOOGLE_CLIENT_SECRET, then the build's local, git-ignored default-credentials.local.json, then empty — and developer enrollment deliberately grants no Google credential, with no server that provisions the pair. So on a dev build Gmail backup cannot send, and the app says so plainly instead of failing obscurely.

  • The CLI backends still work if you install and authenticate one yourself — that is the supported way to run this feature on a source build.
  • With no CLI available, delivery falls to the app's own connected Google account, and a dev build can never establish one: Connect Google refuses up front for the same missing client, so no account is ever connected and the send has no account to send from.
  • The panel shows a plain notice as soon as Setup Backup status loads — this is a developer build, it has no company Google sign-in, so Gmail backup is off here; the installed app has it. The same sentence replaces the generic "check your internet and Gmail connection" copy on the Back up now toast and on the failure-push toast, and it is what the recorded failure message carries into the Settings banner (from the third consecutive failure) and the inbox failure card (from the first).
  • In this state the inbox failure card drops its gog/gws re-authorize remedy, because re-authorizing was never the problem. Its dedup key — and therefore its one-click action — is unchanged.

To turn Gmail backup on in a source build, supply your own Google OAuth client: set MAIN_VITE_GOOGLE_CLIENT_ID and MAIN_VITE_GOOGLE_CLIENT_SECRET, or put the pair in the build's local, git-ignored default-credentials.local.json (what the secrets:seed tool populates on a machine whose vault holds it), then restart or rebuild. Until then the panel keeps saying Gmail backup is off here.

Implementation: isGoogleOAuthClientConfigured() in google-oauth-client.ts is the ONE reading of "this build has a usable client"; missingGoogleClientBackupCopy() in setup-backup-mailer.ts turns it into the wording and keeps the end-user sentence for an official release; setup-backup:get-status ships it to the panel as googleSignInNotice (null when the client is configured). None of this changes the packaged app.

"gog can't open its saved Google sign-in": a locked keyring, not a lost account

gog keeps its Google sign-in in an encrypted file keyring that needs GOG_KEYRING_PASSWORD to open. When the app's own process does not have that password, gog cannot read even one saved account, and on its own it says only "missing --account". That reads like a disconnected account, but the account is fine, and signing in again does not help, because the new sign-in lands in the same locked file.

  • The backup card now says what is actually wrong: "gog can't open its saved Google sign-in", and names the one-time fix: save the gog keyring password once in Omniscio.
  • The one-time fix can now live in the app. Save the password once as the gogKeyringPassword setting (an agent offers it through the input-request prompt and you press Save). The app checks it opens gog's keyring, keeps it encrypted, and hands it only to the gog programs it starts. The older fixes still work: give the app's environment the password (a user-level GOG_KEYRING_PASSWORD, which every program you start can then read, and which wins over the saved one), or move gog to Windows Credential Manager with scripts/gog-switch-to-wincred.mjs --apply, which would leave no password behind. With the current gog (v0.47.1) that move is not possible: a full Google sign-in is larger than the 2560 bytes Windows Credential Manager allows per entry, and gog saves the whole permission list again every time it refreshes. The script checks this first and stops before changing anything or opening a browser, so gog stays on its file keyring with the password, which keeps working.
  • If gog really does have no saved account, or several with none set as the default, the card says that instead and points at gog auth list and gog auth manage. The app never picks an account for you.
  • How the app tells the two apart: google-cli-fallback-contract.md, "The gog runner and its locked keyring".

Schedule

  • Interval: 7 days (BACKUP_INTERVAL_MS in src/main/services/backup/setup-backup-scheduler.ts).
  • Startup delay: 5 minutes after app launch — gives your other services time to settle so the first tick doesn't compete with onboarding.
  • Tick frequency: every 1 hour the scheduler wakes up and asks "is it time?" against lastSetupBackupAt.
  • Dedup: each bundle's content hash (SHA-256 of all entries except manifest.json, sorted alphabetically) is compared against the previous successful one. If nothing has changed since last week, the email is skipped and only lastSetupBackupAt advances. Your inbox doesn't fill up with identical bundles. The hash is exposed as manifest.contentHash inside the bundle and persisted across runs as lastSetupBackupContentHash in AppSettings so the next-week scheduler can skip an identical backup.
  • Failure surfacing: each failed tick increments setupBackupConsecutiveFailures and stores the error message. On the third consecutive failure the scheduler emits the setup-backup:failure-notification push event exactly once — the Settings panel shows a red banner ("Last 3 backups failed: <reason>") and a toast pops in the foreground. A persistent "Setup backup is failing — N consecutive failures" card is also raised in the inbox (and re-raised on every further failure, so it survives a restart and its count stays current) — it clears itself once a send succeeds. See backup-failure-alert-contract.md.
  • Re-entrancy: an in-flight flag prevents two ticks from overlapping. A force: true invocation (from "Back up now") bypasses the too-soon and dedup gates but still respects the in-flight lock.

Restore flow

The Restore dialog runs in two phases — preview, then execute — so you can sanity-check the bundle before any destructive write.

Preview (setup-restore:preview IPC channel):

  1. You pick a .zip / .zip.enc file from disk. Omniscio reads its first four bytes to detect format.
  2. If encrypted, Omniscio runs decryptBundle(bytes, passphrase) to recover the plaintext ZIP. Wrong passphrase or tampered byte → AEAD throws, dialog surfaces Failed to decrypt bundle — wrong passphrase or tampered file.
  3. The ZIP's manifest.json is parsed and validated (version: 1, schema not newer than current, hostname captured for the cross-machine warning).
  4. The dialog shows: bundle hostname, exported-at timestamp, schema version, table row counts, recipe count, skill count, and a list of warnings. The literal warning strings the dialog surfaces are bundle was created on '<host>' (this machine is '<host>') — projects keep the folder locations they had on that machine and must be repointed; skills paths and credentials may not transfer cleanly — review carefully (cross-machine notice; restored projects carry the other machine's folder paths verbatim, so each one has to be repointed) and schema mismatch: bundle v<n>, current v<n>; restore may be incomplete or fail (older-or-newer schema).

Execute (setup-restore:execute IPC channel) — your choice between two modes:

  • Replace mode (recommended for "I want my old setup back"):

    1. VACUUM INTO snapshot first. Omniscio writes a hot pre-restore snapshot of your current mission-control.db to <userData>/backups/pre-restore-<timestamp>.db. The last 3 snapshots are kept; older ones are pruned. If VACUUM INTO fails, the restore aborts before any DELETE runs — you can't lose your current data to a half-finished replace.
    2. Wipes pre-existing rows in the 18 setup tables (DELETE in reverse SETUP_TABLES order, so a child table is cleared before its parent), then INSERTs every bundle row in forward order. A table the bundle did not carry is never cleared — when its database/<table>.json entry is missing, unreadable, over the row cap or the wrong shape, that table keeps its live rows and the restore reports present: false for it, so restoring an older or truncated bundle can no longer empty a library the bundle knows nothing about (this is how Quick Replies used to be lost); a table the bundle DID carry is still replaced exactly, including a present-but-empty one. Foreign keys stay enforced for the whole restore — SQLite ignores PRAGMA foreign_keys inside a transaction — so SETUP_TABLES lists every parent table before the tables that reference it, and a table that references itself (bookmarks) has its rows sorted parents-first before insert. A row whose parent is genuinely missing is refused and counted, never silently kept. Linked data outside the 18 tables survives the wipe: clearing a setup table would otherwise cascade into other tables (a session's tags under a replaced tag, say), so Omniscio sets those rows aside before the wipe and puts each back once the bundle is loaded, as long as what it belongs to is back too; any it could not put back is named in the restore's warnings. (Same mechanism as Import Data: data transfer.)
    3. Overwrites your app settings with the bundle's, minus the same denylist that protected the bundle on the way out (so the restore can't accidentally re-introduce a stale OAuth token).
    4. Wipes ~/.claude/recipes/ and writes the bundle's recipes back in.
    5. For each skill in the bundle: wipes the matching folder under ~/.claude/skills/ and writes the bundle's content.
  • Merge mode (recommended for "I want to add my home machine's setup to my work machine without losing my work setup"):

    1. No pre-restore snapshot — merge is non-destructive by design.
    2. INSERT OR IGNORE each bundle row. Conflicts on PK keep the local copy; the bundle's value is skipped and counted in result.appliedTables[t].skipped.
    3. Settings are preserved unchanged — updateSettings is not called.
    4. Recipes: for each .recipe.json in the bundle, if a file with the same name already exists locally it's skipped; otherwise written.
    5. Skills: same pattern as recipes — existing skill folders are kept, missing ones are pulled from the bundle.

The result object lists every applied table with bundleRowCount, inserted, skipped, and any per-table warnings; the same shape covers settings, recipes, and skills. The dialog renders a green success card with collapsible per-section row counts.

Restore safety

A passphrase-encrypted bundle still arrives over an untrusted channel (your Gmail account, which a phishing attacker might have compromised). The restore code defends against malicious bundles, not just honest ones.

  • Zip-Slip prevention: every zip entry path is checked for .. segments and absolute-path prefixes (/, \, C:\-style drive letters) before grouping. After resolving a target write path, a second path.resolve defense-in-depth check confirms the result is still inside the destination directory. Any entry that fails either check is skipped and counted in appliedSkills.skipped_traversal.
  • Per-skill size cap: 5 MB per skill, 15 MB total across all skills. A skill that would exceed either cap is left out of the bundle, not truncated, and the build records a warning the restore preview shows. Whole-bundle cap: 20 MB — a bundle above that is rejected outright with a clear error.
  • Schema version gate: a bundle whose manifest.schemaVersion is newer than the current DB throws — restoring forward across breaking migrations is unsafe and Omniscio refuses rather than risk corruption. A bundle with an older schema is allowed (schemas are additive) and shows a warning.
  • Manifest validation: a missing or malformed manifest.json, a version != 1 field, or an unsupported field type throws before any DB write.
  • Empty file: a zero-byte bundle is rejected immediately.
  • Column whitelist: every INSERT pulls its column list from PRAGMA table_info(<table>) and filters bundle JSON keys against it. A malicious key like evil; DROP TABLE projects; -- is silently dropped, not interpolated into SQL.
  • VACUUM INTO mandatory in replace mode: if the snapshot fails (disk full, I/O error, locked DB), the restore throws before any DELETE — your current state is preserved. There is no fallback to "skip the snapshot and restore anyway."

Failure surfacing

The Settings panel reads its state from the setup-backup:get-status IPC channel:

  • Last backup: ISO timestamp from lastSetupBackupAt.
  • Next backup: lastSetupBackupAt + 7 days, or "—" if no successful backup has run yet.
  • Encryption: the status card's row reads "Passphrase set" when setupBackupPassphrase is non-empty and "Not encrypted" otherwise. The plaintext passphrase never crosses the IPC boundary out — only a boolean projection (hasPassphrase).
  • Failure banner: shown when setupBackupConsecutiveFailures >= 3, with the latest error message.

When the threshold is crossed (transition from <3 to >=3), the scheduler emits setup-backup:failure-notification once. The Settings panel listens via useIpcListener and shows a toast + refreshes its status. Subsequent failures while still over the threshold do not re-emit — you don't get a toast every hour for the same broken backup.

Limits and non-goals

  • Backup, not chat history. If you need conversation backups, use the automatic local backups (see Local restore points) or Backup Mirror. The setup bundle skips sessions and conversation_messages on purpose.
  • One bundle per week, dedup-aware. Not designed as a versioned snapshot system. Gmail keeps every email, so you do effectively get a 52-bundle history per year — but Omniscio won't help you walk through it. Pick the most recent and restore.
  • Single passphrase. No per-machine passphrases, no key escrow, no recovery code. Lose the passphrase and the bundle is unrecoverable. This is intentional — adding any of those makes the threat model worse, not better.
  • Bundle format v1 only. A future v2 (richer manifest, signed manifests, etc.) would land as a new manifest.version and the restore would gate on it. Today, only v1 is supported.
  • Caps are hard — in two different ways. The whole-bundle cap fails the backup, with an error you'll see in the failure banner. The two skill caps do not fail it: a skill that will not fit is left out of the bundle and named in a manifest warning (shown in the restore preview), so trim your skills folder if you blow the 15 MB skills cap. Nothing is silently truncated — but a skipped skill is absent from the bundle the email carries.

Last verified 2026-10-04