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.
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.