Cross-Device Sync
Sign in on a second computer and your setup is already there — sessions, projects, recipes, automations, bookmarks, your AI Coaching content and non-secret settings, kept end-to-end encrypted. Covers the opt-in switch, device enrollment and the one-time recovery code, what happens to running sessions and scheduled jobs, and the security guarantees.
On this page
Status: available in Settings, OFF by default (opt-in). The
cross-device-synctoggle (Settings → Cross-Device Sync) is the real off-switch — sync runs only when you turn it on, and the change takes effect live (see "Turning it on and off" below). The engine, the live background runner, the new-machine experience + device management, the storage housekeeping (oplog compaction + garbage collection), and the diagnostics readout are all built. One hosted step remains an owner action — a functions-only relay deploy that lights up the GC delete/list ops; core push/pull sync uses the live/t/syncrelay and GC simply no-ops until then (see "Storage housekeeping").
What it is
Sign into Omniscio on any of your computers and your setup is already there — sessions,
projects, recipes, automations, bookmarks, non-secret settings — kept in sync
end-to-end encrypted. The cloud is an encrypted courier, not a new
authority: your local mission-control.db stays the source of truth, and Omniscio's
server holds only ciphertext it cannot read or undetectably tamper with
(zero-knowledge). It evolves the folder-based Backup Mirror
into a seamless, Omniscio-hosted experience — no cloud drive to own or configure.
AI Coaching travels with your setup. Every coaching row the coach writes for you — saved artifacts, bookmarks, goals and their check-ins, the summary of each conversation segment, the facts it extracted about you, your core profile, the insights drawn across your artifacts, the context you pinned and the feedback you wrote about a session — replicates to your other enrolled devices like the rest of your content, inside the same seal. A machine that finished syncing before this shipped queues what it already holds on its next cycle, so turning sync on does not depend on when you first wrote it. The Journal is the exception: its entries stay on the computer you wrote them on.
Secrets never sync (API keys, OAuth tokens): they're per-machine and re-approved once via the existing Post-Restore Credential Wizard.
Your Vault notes do not sync either. Cross-Device Sync carries no Vault data — no notes, no version history, no bookmarks or tags. To use the same notes on two computers, keep the vault folder in a folder-sync service and point each computer at it. See KMS.
A new computer gets what you already had. Turning sync on uploads your existing install once (projects, sessions and their history), not just the changes you make from then on — so signing in on a new machine brings your whole setup across, not only rows that happened to change afterwards. That first upload runs in the background and picks up where it stopped if the app is closed mid-way; while it is still going the status says so rather than "Synced".
Tasks do not sync here yet. Your Tasks lists travel between computers only through the folder-based Backup Mirror, so if you use Tasks on more than one computer, keep Backup Mirror on alongside sync. The section says so itself and links straight to Settings → Backup & Restore, so the exclusion is visible at the point where sync promises your saved work follows you, rather than only in this library.
Where to find it
Cross-Device Sync has its own section in Settings, reached from the app's Settings gear — that section holds the on/off toggle, your device list, the key-rotation control, and the card that offers to switch you over from the folder-based backup if you were using it. A read-only summary of what sync has been doing appears in Settings → Diagnostics. When another computer asks to join, you are not expected to go looking for any of this: the request arrives as a card in your inbox.
How it behaves
Scheduled jobs run on one computer (not twice)
Your scheduled jobs — crons and scheduled recipes — sync like the rest of your setup, but they run on only one of your computers, not on each one at the same time. Without this a synced cron would fire on every signed-in computer at once, doing the work (and spending) twice.
- A cron runs on the computer that owns it. A cron you create binds to the computer you made it on; move it by editing it on the computer you want it to run on.
- Editing an existing cron binds it. Crons created before you turned sync on keep behaving as before until you next edit one — that edit binds it to the current computer. (Scheduled recipes bind automatically the next time they run.)
- Omniscio's own background jobs still run on every computer — routine maintenance like folder cleanup and drift checks stays per-computer. One known limit: two computers that both hold an Omniscio source checkout at DIFFERENT paths share one row per background job, and the computer that started last writes its own path into it, so the other skips that job until it restarts.
- A job that works in a folder only one computer has stays on that computer. When a script job that no single computer owns (Omniscio's own background jobs, or a job not yet claimed) names a working folder that does not exist on this computer, this computer quietly skips it: no failed run and no automatic fix, and no "job overdue" card while another computer keeps running it. If no computer has run the job for a day, the overdue card does appear here too. A job this computer owns still fails loudly if its folder goes missing — that is a real problem here.
- A scheduled check-in (a session wake) runs on the computer where its session runs. A wake that nudges a session — an Overseer's heartbeat or review, or an agent's own check-back — fires only on the computer that runs that session, whichever computer created or last edited it. Your other computers never claim it, so it can no longer be lost as "Fire dropped — the schedule cursor advanced before this fire was claimed". A wake another computer had already taken over moves back to the session's computer on its next fire.
- An automatic fix never switches a job off on your other computers. When a failed job starts a fix session, the job is paused only if this computer is the one place it runs. A job your other computers also run stays on; the fix happens here without stopping it there.
- Remove a computer and its jobs move on. De-enroll a computer that owned some jobs and they're released for another computer to pick up — they never silently stop.
This is fully effective once both computers are on the updated app. See
cross-device-sync-contract.md
(device-scoped-execution).
Sessions from another computer come over Paused (readable here, continued there)
A session that was running on one computer arrives on your others as Paused, not running — its live Claude process only exists on the machine that started it, so nothing auto-runs (and nothing double-charges) when your setup lands elsewhere. Open one and its full history is there to read, and the computer that started it continues it exactly where it left off. Only that computer can continue it, so a reply sent from another one is answered with a plain sentence saying where the session lives — not a database error. A session you're genuinely running on the receiving computer is never touched.
Only one computer can change a session. The computer that started it owns it; everywhere else the conversation is readable and sending is closed off, with a line above the box saying why. That is deliberate — two computers writing one conversation would fork it.
The same rule covers a request an agent approves for you. Pause, unpause, snooze and archive on a session that belongs to another computer are declined the moment they are asked for, with that same sentence — they never become an approval card you could click and then watch fail. If an approval does fail for this reason (the session changed hands after the card was raised), it closes with the reason and the session that asked is told, rather than sitting there waiting.
Continuing a session on this computer
When you want to carry on from the computer you're sitting at, that line carries one button: Continue on this computer.
- Clicking it asks you to confirm, because it moves the conversation rather than copying it.
- On confirm, this computer owns the session and you can type straight away. The whole conversation comes with it — nothing is copied, moved out or lost.
- Your other computer stops being able to change it the next time it syncs, not the instant you click. Until then it can still write, so treat the move as "it takes effect shortly" rather than "instantly locked".
- If that computer is still running this session, stop it there first. Once the move reaches it, the run keeps going but nothing it writes is saved — its status updates and new messages are refused, and the work it produces never lands in the transcript.
- The other computer keeps its own readable copy of the conversation. If it turns out to be the one you want, it shows the same button and adopting it back moves ownership home again.
It needs Cross-Device Sync on, on this computer. A computer that never syncs again never learns about the move and keeps writing — which is why the move is worth making on the machine you actually use.
See cross-device-sync-contract.md (session-status-device-local,
session-rows-have-one-writer) and
session-ownership-transfer-contract.md.
Turning it on and off
Cross-Device Sync is OFF by default — it's opt-in. The Enable Cross-Device Sync toggle in its Settings section is the real switch:
- Off by default. With the toggle off, the background sync runner never starts, installs no capture triggers, and does nothing — for every user, even signed in. Nothing leaves your machine until you opt in.
- Takes effect live. Flipping it on starts sync and off stops it immediately — no restart — from any surface (the desktop UI, the CLI, or the mobile app); turning it off tears down the runner and its capture triggers at once.
- The toggle reflects the real state. It reads on only when you've actually enabled it — it won't snap back to on when it's off.
- It never slows the app. The background loop paces itself, leaving a minimum rest between sync cycles, so even on a busy machine with many sessions it can't run back-to-back and compete with what you're doing (the app's "never slow the user" rule) — and the pacing can't starve it, so your devices still stay in sync.
Under the hood the runner gates on three things — the feature is visible, you've
enabled it, and you're signed in — and a settings change reconciles it on the spot.
See cross-device-sync-contract.md
(runner-inert-for-real-users).
Coming from folder Backup Mirror?
If you already use the folder-based Backup Mirror, Cross-Device Sync offers a one-time, additive way to switch. Turn the feature on and you'll see a "Switch from Backup Mirror to Cross-Device Sync" card in the sync settings (plus a matching nudge in Settings → Backup & Restore). Adopting is non-destructive — your Backup Mirror keeps working, nothing is deleted, and setting up sync just enrolls this device (the same flow below), so your existing setup rides the encrypted courier from now on. Once you're synced, an optional hint lets you turn folder Backup Mirror off if you no longer want a second backup — reversible anytime. Keep Backup Mirror on if you use Tasks on more than one computer: tasks travel only through it. The offer appears only while the feature is on (it's off by default), and it's shown at most once.
The key model (why there's a recovery code, not a password)
One random data key (DK) encrypts everything. Omniscio uses federated sign-in (Google), so there's no password to derive a key from without the server seeing it — instead the unlock is device enrollment (the Signal / 1Password linking pattern):
- The first device generates the DK, seals it under a machine-local key in the OS keychain, and uploads two wrapped copies to the locker: a recovery-code wrap and a device wrap. It shows the recovery code once.
- Every later device must enroll to get the DK — two ways (below).
- The server only ever stores wrapped copies of the DK; day-to-day unlock is silent (the device-local key is already present).
The recovery code is high-entropy (≥128-bit, Crockford base32) so the recovery-wrapped DK can't be brute-forced offline. It is shown once — the app makes you tick "I've saved my recovery code" before you can continue, and there is no way to re-fetch it — so store it somewhere durable (a password manager). It is your only break-glass: lose every enrolled device and the recovery code → the data is permanently unrecoverable (the price of true zero-knowledge; the server holds only wrapped copies it cannot open). A key rotation mints a new code and retires the old one, so save the new one each time you rotate.
The two everyday flows
Steady state (a device you already use): a local change → debounce → append an
encrypted oplog segment → atomically advance the manifest. Quiet and continuous, and it
self-heals through a key rotation (syncCycleWithRotationRecovery). A busy computer syncs at
most every 30 seconds, so a change normally reaches your other devices within about a minute.
When nothing changed, a sync round asks the cloud "has it changed?" and downloads nothing. A throttled
maintenance pass rides the same cycle to keep storage bounded (see "Storage
housekeeping" below).
New machine (Phase 3): install Omniscio → sign in → enroll this device → the app downloads + decrypts + replays the oplog to rebuild the local DB → the credential wizard walks you through re-approving accounts → live. The modal offers an optional name for this device first (see "Device management" below — you can also set it later); the name is applied once enrollment succeeds, so a failure there never blocks the rebuild. Two enroll paths, offered as tabs in the enrollment modal:
- Approve on another device — this device publishes a pending request (its public key) to your device registry; a device you already use re-wraps the DK to that key (ECIES over X25519) and drops it in the locker; this device polls, unwraps with its machine-bound private key, and finishes. Both screens show a key fingerprint so you can eyeball-match them: the joining device shows the one derived from its OWN public key, the approving device shows the pending request's, and you compare the two. Each is 128 bits of the key's SHA-256, grouped in fours for reading aloud — long enough that a server in the middle cannot mint a lookalike key that lands on the same code.
- Enter recovery code — paste the one-time code; it unwraps the recovery-wrapped DK directly.
You get told, you don't have to go looking. When a new device asks to join by the "Approve on another device" path, one of your already-set-up computers notices within about a minute and pops up a "A new device wants to join your sync" card in the inbox (plus a native notification if the app isn't focused). One click on it takes you straight to the approval screen — no hunting through Settings. It's still a real approval, not a blind one-tap: you confirm the new device's short code there before approving (approving lets it decrypt your synced data). The card clears itself once the device is approved, denied, or gone, and — like everything here — it only appears while sync is turned on. Approving stays a human-at-the-computer action: an AI agent or your phone can't approve a device for you. If several devices ask at once, they collapse into one card; a long-abandoned request is ignored.
And the new machine gets told too — it can't be left quietly un-joined. The prompt
above is the approving side; the waiting side has its own. While a computer is signed in
to an account that already syncs but has not joined it yet, that computer shows its own
"This computer has not joined your sync yet" card (plus a native notification if the
app isn't focused), and it clears itself the moment you join. That matters because the
enrollment window that opens by itself lives in one app window's memory: dismiss it, never
open Settings, or have the very first check fail, and nothing else used to say a word. The
check itself no longer gives up either — it retries on a widening backoff, tells you if it
runs out of tries (with a Try again button rather than silence), and re-runs the moment
you finish signing in, so a computer switched on mid-sign-in lands in the join window
instead of waiting for an app restart. Neither the card nor the window joins or approves
anything on its own: they only take you there, and the fingerprint check on your other
computer is untouched. See enrollment-never-silent in the contract.
Restore is additive-merge, never a wipe — rows that exist only locally are kept (remote deletes still apply), so adopting sync on a machine that already has data merges rather than destroys. When a remote delete does apply — a session or project you removed on another computer — its dependents are cleared with it (its messages, plus device-local extras like terminal history or tracker rows), so the deletion lands cleanly on every computer instead of leaving orphaned leftovers behind.
A delete sticks. If you deleted something here and another computer had
edited that same row before it heard about the delete, that older edit no longer
brings the row back: the delete you made on the computer that holds the row wins,
whichever way the two changes reach each other. Changing your mind still works —
un-deleting something on that computer syncs out as an ordinary change. See
cross-device-sync-contract.md
(a-soft-deleted-row-is-never-resurrected-by-a-stale-edit).
Same folder or same name on both computers? If each computer independently created a
project for the same folder — or a tag with the same name — sync treats them as one and
merges them instead of stalling: your computer keeps its own copy and the other computer's
chats (and links) are filed under it, so you end up with a single project/tag carrying all its
history, never a duplicate. See
cross-device-sync-contract.md
(unique-collision-converges).
Attachments follow the same rule — a file deleted on one device is removed on your other devices on the next pull, and SAFELY: each device remembers the set it last synced, so it never deletes a file still referenced by the current set, one you made locally and haven't uploaded yet, or one you've since edited (your edit wins and re-syncs). It's behind the same default-off gate; a delete on the origin device is no longer resurrected by its own next pull.
Computers on different app versions? Sync pauses cleanly
Your setup evolves between releases — a new feature can add a new field to your projects,
sessions, and the rest. If one computer is a version or two behind and a newer one sends it
data shaped for a field the older one doesn't have yet, sync pauses on the older computer
with a clear "update Omniscio on this device to resume syncing" message — it never crashes,
and nothing is half-applied (the whole sync attempt rolls back). The same clean pause covers a
value the older version's rules reject, not only a missing field — it shows the update
message rather than a generic "couldn't save" bug notice. Update the older computer and
sync resumes on its own; the pause clears itself. A newer computer receiving older data is
unaffected — a field the older computer didn't send just takes its normal default. See
cross-device-sync-contract.md
(replay-schema-drift-pauses-cleanly).
Storage housekeeping — compaction + GC (keeps cost bounded)
Left alone, the oplog would grow forever (every change is an append), so a maintenance pass — throttled (≥1h) and riding the normal sync cycle so it never blocks a sync — keeps both the cloud footprint and a new-machine restore bounded to current state, not lifetime history:
- Compaction folds the accumulated oplog objects into a base snapshot (a
delete-preserving coalesce — last write wins per row, so deletions survive) and resets the
live oplog. A new machine applies the snapshot first, then the recent tail. A
readerFormatgate makes an older app refuse a compacted manifest rather than silently drop the folded history, and the snapshot sits inside the manifest MAC. - Garbage collection reclaims the now-orphaned objects, but only after they've been unreferenced across two maintenance passes (≥1h apart) — so an object mid-upload on another device is never collected. It never touches an object the current manifest (including the base snapshot) still references, and it holds even against a lying object list.
- Account deletion purges your whole locker server-side (best-effort, retried by a daily reconciliation sweep) — a deleted account's devices may never run again to clean up after themselves.
The relay's delete + list operations back GC; until they're deployed the client stays optimistic and GC simply no-ops (the feature is off by default regardless).
When it fails: what the status says, and what to do
Sync runs quietly, so a problem reaches you in exactly two places: an inbox card, and the status line on its settings page. Both are designed so you never have to guess whether it is working.
The card. A genuine failure raises "Cross-Device Sync is failing": the body carries the most recent error in plain words, then says your local data is safe and unchanged and that your devices are not syncing right now. Its Open Cross-Device Sync settings button takes you straight to the sync section (it lives under Settings → Data & Security → Cross-Device Sync). The card clears itself the moment a sync succeeds. A second, separate card — "Cross-Device Sync cleanup is failing" — appears only after six consecutive failed housekeeping passes. It is deliberately quieter: your devices keep syncing and your data is safe; what grows is the space the cleanup would have reclaimed. It also clears itself once a cleanup pass succeeds.
The status line. In Settings → Diagnostics, the "Cross-device sync diagnostics" card shows one plain-language status plus the last-synced time and the last error. Most statuses are not failures — they are sync deliberately waiting for something, and each one says what:
| Status | What it means | What to do |
|---|---|---|
| Synced | The last cycle completed | Nothing |
| Syncing… | A cycle is running now | Nothing |
| Idle | Enabled but nothing to do right now | Nothing |
| Paused — offline | No network connection | Reconnect; it resumes on its own |
| Paused — metered connection | You are on a connection marked metered (a phone hotspot, say) | Nothing, if that is what you want — it resumes on an unmetered connection |
| Paused — daily limit reached | The day's sync allowance is spent | Nothing; it resumes tomorrow |
| Sign in to sync | The account signed out | Sign in; sync resumes |
| Set up sync on this device | This computer has not joined your sync, or its key can no longer be decrypted | Enroll it (or re-enroll if it was already joined) — see the enrollment flow above |
| Sync failed | A real, unexpected error — the only status that raises the card | Nothing to click: the next cycle retries. Read the last error on this card; if it keeps failing, open Settings → Diagnostics → Export diagnostic bundle and send it to support |
Two honest notes about Sync failed:
- Your data is not at risk. A failed cycle rolls back rather than half-applying, so your local database is the same as before the attempt, and the other devices are untouched. What is wrong is the transfer, not your work.
- The detail is real, not a shrug. The diagnostics card keeps the last several cycles — objects
applied, conflicts, bytes moved, and any failure reason — so a report can say what actually
failed instead of "it says failed". Those same numbers are written to the app log as
[sync-metrics]lines.
Worktree and attachment capture/restore on their way between computers is the one area where a
refusal is expected rather than alarming: a snapshot that cannot be represented safely is
refused rather than approximated, and the session itself still arrives (see "Sessions from another
computer come over Paused" above). If you are chasing one of those, the diagnostics card's recent
cycles and the [sync-metrics] log lines are where the refusal is named.
Diagnostics readout (observability)
Because the runner works quietly in the background, a read-only diagnostics readout in Settings → Diagnostics ("Cross-device sync diagnostics") shows what it actually did — visible only while the feature flag is on, so a real user never sees it:
- Current status — synced / syncing / paused (offline · metered · daily-limit) / needs sign-in or enrollment / failed, plus the last-synced time and the last humanized error.
- Running totals — cycles run, failures, bytes uploaded/downloaded, objects compacted, orphans reclaimed (since the app started or the last account switch).
- Recent cycles — the last several sync cycles: objects applied, conflicts, bytes moved up and down, the manifest version, and any failure reason.
- Recent maintenance — the last several housekeeping passes: whether compaction folded (and how many objects → snapshot bytes), orphans reclaimed, and orphans still pending their second strike.
- Locker size / health — total objects in your cloud locker, how many the current manifest references (the live set), and how many are orphaned garbage, refreshed on each maintenance pass.
Everything is zero-knowledge-safe — it carries only counts, byte totals, versions, timestamps,
and already-humanized errors, never a secret, key byte, row value, or object name. The same numbers
are also written to the app log as structured [sync-metrics] lines for after-the-fact debugging.
The whole readout stays behind the default-off gate: with sync disabled nothing is recorded and the
readout is empty, and it resets when you switch accounts.
Device management (Phase 3, in the Settings section)
- Your devices — a per-user list (each device is public metadata only:
label, key fingerprint, last-seen; no key material). It lives in Firestore
user_sync_devices/{uid}/devices/{deviceId}, readable/writable only by you. - Naming a device — setting up sync asks you to name the computer before it
provisions, and the enrollment modal offers an optional name for a machine
joining later. Rename (the pencil on any row) changes it afterwards, from any
of your machines — including the one you are sitting at, whose row otherwise has
no actions. Without a name a device falls back to the neutral "This device",
which is unambiguous on one machine and useless on two, so every row you have not
named reads identically. The app will never name a device for you from the OS
hostname: the label is the one sync field stored in the cloud as readable
plaintext, and consumer hostnames embed the owner's real name — so the dialog
says so and lets you choose. The rename writes
labelalone (it cannot disturb the public key device-approval depends on) and carries an exists-precondition, so renaming a device that was removed on another machine fails cleanly instead of resurrecting a ghost record. - De-enroll — removes a device from your registry.
- Rotate keys — the security response to a lost/compromised device: re-encrypts the whole locker under a brand-new DK and revokes any removed device (it is simply not re-wrapped, so it can read nothing new), while your remaining devices adopt the new key automatically on their next sync. Yields a new one-time recovery code. Removing a device then rotating is the full revoke. A rotation interrupted part-way (a crash, a dropped connection) is resumable: the next attempt finishes that same rotation rather than starting a new one, so nothing is ever left sealed under a key the app no longer holds — just try again. (A device doing its very first restore at the exact instant a rotation runs retries until it completes — a documented residual window.)
Removing Journal-based coaching facts from your other computers
Your Journal never leaves the computer you wrote it on, and neither does any AI Coaching fact learned from it — that has been true since the exclusion landed. Facts learned from a Journal entry before that exclusion, however, had already been copied into your saved sync data, so they can still sit on your other computers.
The Journal-based coaching facts on your other computers card in Settings → Cross-Device Sync cleans those up:
- It counts first. "Check how many" asks the app how many coaching facts on this computer were learned from its Journal. Nothing is removed until you press the second button and confirm.
- Your copies stay. The card never deletes anything on this computer. What it does is ask the sync service to remove the other computers' copies, so the ones here are exactly as you left them.
- It only touches facts whose Journal source is on this computer — a fact whose Journal entry lives on another machine is that machine's original, not a copy, and it is never selected. A fact you already moved to Recently deleted is still cleaned up elsewhere. For the same reason, a fact a Journal entry merely also taught is left alone.
- It is per computer. Each computer keeps its own Journal locally, so if you also journal on another machine, its own Journal-based facts are cleaned by running this on that machine.
- The removal is permanent on the other computers once it propagates. Your copies here are untouched, and a goal the AI created from one of these facts is not removed.
- It travels with the next sync. The removal is queued and your other computers apply it the next time they sync; a later edit of one of these facts is never sent back out, so the copy cannot reappear.
Security guarantees (never-regress)
- Zero-knowledge — the server only ever holds ciphertext + wrapped DK copies;
no plaintext row, DK byte, or
enc:secret ever leaves a machine. - Cross-tenant isolation — you can reach ONLY your own locker (the relay
derives the storage prefix from your verified token, never the request body) and
ONLY your own device registry (
request.auth.uid == uid). - Provisioned accounts only — the sync and portable-backup relays mint nothing
for a bare Firebase Auth user: the token must carry a verified email AND a
users/{uid}profile that exists and is not disabled, so an unprovisionedaccounts:signUpaccount (or a fresh UID minted to dodge a ban) gets no quota. Every write URL additionally pins a per-object byte ceiling. - The sync IPC actions are classified human-only (
security-boundary-human-onlyin the CLI-parity manifest): an AI agent can never enroll a device, approve one, or rotate your keys via the CLI — each needs your physical device and/or recovery code.
Related
The folder-based Backup Mirror is the older way to get the same outcome, and the page explains when to keep it alongside sync. Secrets deliberately do not travel, so a restored machine re-approves them through the Post-Restore Credential Wizard. What sync does to your account when you leave is on the account deletion and reset page, and the setup that sync replaces as the everyday way to move data between machines is Data Transfer. To drive a session live on another of your computers rather than copy its history, see Your other computers; a session Sync already copied here is never listed a second time.
Last verified 2026-09-28