Skip to content

How Cloud Sync works (technical)

Your data lives on your devices. Cloud Sync keeps a copy in the cloud: it is your backup, and on Pro it keeps all your devices the same. This page shows the parts inside it, for curious readers. You do not need any of it to use Kaizendex.

The short version

  • Every change you make is saved on your device first, as one line in a log.
  • On Pro, the line goes to your cloud box, your own small private database in the cloud. It puts the lines in order and passes them to your other devices within seconds. Photos and files go to file storage (R2).
  • On Free, there is no cloud box. Your one device keeps a sealed copy in file storage, and updates it a few minutes after each change.
  • Everything is encrypted on the network and on disk. Collections you set to end-to-end encrypted are also locked on your device, with keys only your devices hold.
  • This device only data never leaves the device.
Your laptop saves each change first, then sends one log line. On Pro, the line goes to your cloud box, a Durable Object with your own small database, which orders the lines and runs your agents; photos and files go to file storage (R2), one copy per fingerprint. On Free there is no cloud box: your device keeps a sealed copy in R2, sealed by the device first and updated a few minutes after a change. Everything is encrypted on the wire and on disk, and end-to-end if you choose. Data set to This device only is dropped by the sync filter and never leaves the device.Your laptopsaves the change firstthen sends one log lineThis device onlythe sync filter drops it:it never leaves the deviceCloud SyncCloud box (Pro)a Durable Object:your own small databaseorders lines, runs agentsFile storage (R2)photos and files,one copy per fingerprintFree: a sealed copy (in R2)no cloud box; sealed by your device firstupdated a few minutes after a changeTLS on the wire · encrypted on disk · end-to-end if you choose
Solid: Pro, where the cloud box orders every change. Dashed: Free, where your one device keeps a sealed copy. This device only never leaves.

The log of changes

Kaizendex never sends “the whole entry” around. It sends changes.

  • Each change is one line. A line says who made it (you, the AI, a script, an import), what changed, when, from which device, and why (which chat or automation).
  • Lines are ordered. Each line carries a stamp from a hybrid logical clock (a clock that mixes real time with a counter), so every device agrees on the same order, even after time offline.
  • Values merge field by field. Your laptop changes “Morning run” from 5.0 to 5.2 km while your phone adds a note. Both changes stay. If two devices change the same field, the later edit wins, and the other value stays in history.
  • Text merges word by word. A Block page field is a CRDT (a data type built so that edits from many places always merge the same way; we use Loro). Two people can type in one note at once and lose nothing.
  • No common base, no silent merge. To merge, the engine needs the earlier version both sides started from (the base). When it has none, for example for a file that comes back from an old backup, it never merges in silence. It keeps both versions as a conflict, and you pick one.
  • The same log does more. History, Undo and the AI receipt all read it. See History and undo.

A device that was offline asks for the lines after the last one it has (“what is new after line 4,812?”) and gets only those.

Many deletes at once pause. Deletes that come from outside the app (files gone from your folder, or a device that sends a pile of old deletes after being away) wait when there are many at once. Every device shows “A device wants to delete 412 entries”, with Delete and Keep. Your own deletes in the app do not pause: they have Undo. Restore from my folder and going back to a backup only add or update; they never delete.

Cloud drives. If your folder sits in a cloud drive, the same change can arrive twice: through the drive and through Cloud Sync. Cloud Sync wins, and the drive’s copy is ignored. A file the drive moved off your disk (“online only”) never counts as a delete.

Pro: the cloud box and file storage

The cloud box is one private, small database per person, at Cloudflare. Technically it is a Durable Object: a tiny program with its own SQLite database. Exactly one copy of your box runs in the world at a time, and nothing else can touch its database.

  • It has the same tables as your devices, so the cloud copy is one more device.
  • Your box is chosen from your verified sign-in, and the box checks it again. Parts of our cloud that take outside traffic (webhooks, chat channels, public pages) cannot open a box directly. Public pages are a published copy, made when you publish.
  • For everyday sync, it checks that a line comes from one of your signed-in devices, numbers it, stores it and pushes it to your other devices.
  • A protected change (Where, AI, sharing, approvals, devices, Delete for good and the rest) must carry a signature that your device makes only after a fresh check of you. The box and every device ignore a protected change without it. See Changes only you can make.
  • It sleeps when nobody needs it, and wakes for a device, a schedule, a message or incoming data.
  • It is also your agents’ home. They run there while your devices are off, and their work syncs to your devices like any other device’s. Each agent is a registered device with its own keys. See The agent home.
  • Each person’s box is separate, so a heavy user never slows anyone else down. Your data is physically apart from everyone else’s.

File storage (R2) is Cloudflare’s file storage. Photos and files go there, not into the cloud box. The box keeps only a record of each file: its name, size, fingerprint and entry.

  • A fingerprint is a short code worked out from the file’s bytes. A file is stored once per fingerprint, so two copies of the same photo use the space once. This works per person only, never across people.
  • Uploads run by themselves. Our Worker (a small program on our cloud) first checks the file’s size and your allowance. Then the file goes to file storage in parts, in the background. After a dropped connection or a restart, the upload goes on where it stopped. A file can be up to 2 GB.
  • Pro includes 50 GB of files. Desktops keep every original. Phones keep previews and recent files, and fetch an original when you open it.

Free: a sealed copy in file storage

Free has Cloud Sync for one device, and no cloud box. Instead:

  • Your device seals (encrypts) a copy of your data and files before upload, and stores it in file storage. We store only scrambled bytes.
  • The copy updates a few minutes after a change, not within seconds. One device needs no live ordering.
  • Up to 200 MB of files go in. Your data (text, numbers, settings) has no practical limit. Files past 200 MB stay only on your device, and the app says so.
  • A recovery copy of the key comes back after an Approve or a 72-hour wait. We keep it with your account, so a new device can open the copy. It goes only to a new device you approved on a device you have, or after a 72-hour wait. A passkey bound to one device (a security key, or a passkey saved only on one device) skips the wait, and so do your recovery words, if you turned on end-to-end; a passkey synced by Apple or Google does not. A separate key service wraps the recovery copy, so no one person on our side can open it with data access alone, and every release shows in your log. Still, we could open the sealed copy, and the app never says we cannot.
  • Only your current device may write the copy, and earlier versions are kept. So a bad or old upload never replaces a good one.
  • End-to-end collections are locked first, with your own keys, before they go into the sealed copy. The recovery copy of the sealed copy’s key does not open them.
  • Data from outside services (for example Whoop) waits in a sealed inbox in file storage until your device collects it.

There are no agents in the cloud on Free, because there is no cloud box to run them.

The layers of encryption

Layer What it is Who could read the data
On the wire TLS on every connection, the same lock as in your browser’s address bar Kaizendex, but not someone listening on the network
At rest Cloudflare encrypts every cloud box, every file in R2 and every account row on its disks Kaizendex, but not someone with a stolen disk
Kept apart one box per person; access rules let only your devices reach it technically Kaizendex: a rogue insider, a court order or a serious bug could. We do not look.
End-to-end (optional, per collection or entry) your devices lock the data before it leaves only your devices

How end-to-end works:

  • The engine locks every line, value, Block page text, photo and thumbnail with XChaCha20-Poly1305 before it leaves the device. The cloud box still orders and passes on the lines; it cannot read them.
  • Your devices pass keys to each other with X25519, for example when you tap Approve for a new device. They sign their lines with Ed25519, so the cloud box can check that a line came from one of your devices without reading it.
  • The 6-digit number on an Approve tap is worked out by both devices from their own keys. Our server does not send it, so a match proves the two devices talk to each other directly.
  • Numbered and chained. Every device numbers its lines and links each one to the one before. If a line goes missing or is played back twice, your devices notice and show it.
  • No shared end-to-end collections. Sharing an end-to-end collection with people turns end-to-end off for it, after a warning. So no end-to-end key is ever shared between people.
  • Two ways to unlock. Turning on end-to-end makes your 12 recovery words. It turns on only when you have two ways to unlock: this device plus the words, or this device plus another of your devices. A passkey that can unlock (the WebAuthn PRF feature, used with Face ID) is a bonus where it works. We never hold your end-to-end key.
  • Removing a device changes the key of every end-to-end collection it could read.
  • Restore from my folder makes a new key. If you still have another device, it must approve the new key. The old cloud copy is kept 30 days before it is replaced.
  • If you also set an encryption password, the key is made from it with Argon2id, which makes guessing very slow.
  • Every device keeps its private key in the device’s safe chip: the Secure Enclave (Apple), the Keystore (Android), the TPM (Windows), or a browser key that cannot be copied out.
  • All of this comes from audited libraries. We do not write our own cryptography. An outside security audit comes before end-to-end encryption launches (stage 7).

More: End-to-end encryption.

What “This device only” means technically

A collection or entry set to This device only is stored only in that device’s database (and, on the desktop, its folder). The sync filter, the step that picks which lines leave the device, drops every line about it. So nothing about it leaves: not its values, not its files, not even its name. It is not in the cloud box or the sealed copy.

A link to it from a synced entry travels only as a hidden id, so your other devices show “A private item”. It is never sent to a cloud AI model, and “Version this folder with Git” never pushes it.

In a browser linked to the desktop app, “this device” is the computer: the data lives in the desktop app.

If you turn Cloud Sync off completely (only possible in the desktop app), every collection behaves like this, and you back up your ~/Kaizendex folder yourself.

Delete for good, in every copy

Delete for good removes an item at once from the cloud box or the sealed copy, and from each device as it next connects. The cloud’s older copies (restore points and old file versions in R2) expire within 30 days, and so do the desktop app’s own backups. Copies outside our reach, such as your Git history, a cloud drive or an export, stay. See Trash.

What we do not publish