Sync & security
ResearchOS syncs through a server you control, and that server only ever stores ciphertext. This page explains precisely what that means.
Local-first, always
Your workspace on disk is the source of truth. The app works fully offline; sync is a replication layer. Every change also appends an operation to a local journal, inside the same database transaction. Syncing = push my new operations, pull everyone else's.
The key hierarchy
- Your passphrase derives a key (argon2id) that wraps a random master key — the master key never exists unwrapped anywhere but your devices.
- A recovery code, generated once at registration, wraps the same master key. Forgot the passphrase? The recovery flow unwraps the master key on your device and sets a new passphrase. Lose both, and your synced data is unrecoverable — by design, for everyone including the server operator.
- Each synced workspace has its own space key, wrapped by your master key. Operations and files are encrypted with it (XSalsa20-Poly1305) before leaving your machine.
What the server sees
| Stored as ciphertext | Visible metadata |
|---|---|
| Note titles & bodies, todo texts, event details, run commands/params/metrics, PDFs, attachments, chat messages, the compass | Account email, device names, entity types, ids, timestamps, sizes, space membership |
This blindness is enforced by automated tests that dump the server's database after a full sync and search for known plaintext.
Conflicts
Merging is per-field: the newest change wins, ordered by hybrid logical clocks so "newest" is well-defined even across offline devices. For long texts, the losing version is kept as a revision — nothing is silently discarded. Deletions travel as tombstones.
Sharing is explicit
Every user's spaces are isolated — by server authorization and by cryptography (another user's data would be undecryptable ciphertext even if authorization failed; tests attempt exactly that). Sharing happens only through sealed-box invites: the space key is encrypted to the invitee's device public key, relayed — unreadable — by the server.
Sealed logbook entries
Sealing computes a sha-256 hash over the entry's canonical content, chained to the previous seal. The store refuses any later edit or deletion; verification recomputes the chain and localizes tampering to the exact entry. This is tamper-evidence, not notarization — anchoring the chain to an external timestamping service is on the roadmap.
If the server dies
Nothing is lost: local data is the truth, on every device. Re-create the space and any one device re-uploads the full history.