The browser and the desktop app
On a computer with the desktop app, your browser links to the desktop app. So there is one copy of your data on that computer, and the browser stores none of it.
The desktop app serves the app to your browser itself, from the code that ships inside it. Your browser pairs with it once, and only that computer can reach it.
What works today
The link is built. Before the web app is online, you open it at a local address.
-
Start the desktop app.
-
In Chrome, open
http://kaizendex.localhost:47321. The page asks for a code. -
In the desktop app’s tray menu, click Pair a browser. The desktop app shows a 6-digit code. It works for 5 minutes.
-
Type the code in the browser. The browser is paired, and it opens your data.
Example: you tick “Morning run” as done in Chrome. The desktop app shows the tick at once, and
Morning run.md in your folder changes too. History says the change came from you, in
“Chrome”.
How it stays safe:
- Only this computer. The desktop app listens on
127.0.0.1:47321, an address other computers cannot reach. It answers only to the namekaizendex.localhost:47321. A request with any other name is refused. - Only paired browsers. A paired browser gets its own long secret in a cookie that page
code cannot read and other sites cannot send. The desktop app keeps only a fingerprint of the
secret (a SHA-256 hash), in
link\browsers.jsonin its data folder. - Only this page. Every save, and the live connection, must come from the desktop app’s own page. A request from another website is refused.
- Wrong codes add up. After 5 wrong tries in total, the link locks, even if the browser asked for a new code or a code ran out of time. Click Pair a browser in the desktop app again for 5 new tries.
- Nothing is lost when the connection drops. The browser reconnects and gets the changes it missed. If it missed too many, it reloads them all.
- The page comes from inside the desktop app, not from the web.
- Your OpenRouter key stays in the desktop app. A paired browser chats with it but never
gets it. Its Settings → Plan & billing → Your OpenRouter key shows the same masked key and
status as the desktop app, for example
sk-or-v1-f33••••••••••••••••4cc6and “Connected to OpenRouter”. To save, replace or remove the key, use the desktop app.
If another program already uses port 47321, the desktop app opens without the link.
Not built yet: Open through the desktop app on app.kaizendex.com, and the fresh unlock
for end-to-end collections (locked and Hidden items have it today).
One copy per computer
- The browser reads and saves through the desktop app’s engine. The engine is the part of the app that checks and saves every change.
- So the computer has one database and one
~/Kaizendexfolder. - The browser stores none of your data and none of your files. It keeps no database in browser storage and no file cache.
- It holds only what is on screen, in memory. So every click still paints at once. See Why everything is instant.
An example
-
In Chrome, you make a collection, “Super private”. You set its Where setting to This device only.
-
You add an entry to it: “Hello world”.
-
The browser passes the entry to the desktop app. The desktop app saves it in its database, on your computer.
-
Within seconds, the file
~/Kaizendex/Collections/Super private/Hello world.mdappears. -
“Super private” never goes to Cloud Sync or to your other devices. Its one device is this computer.
This works offline too. The link runs on your computer, not over the internet.
This works the same on Free and on Pro. Your other collections stay in Cloud Sync, and “Super private” stays out of it.
Pairing a browser, once
-
Open
app.kaizendex.comin a browser on the computer with the desktop app. It offers Open through the desktop app. You can also open it from the desktop app’s tray menu. -
The browser opens the desktop app’s own page, at a local address on this computer.
-
The desktop app shows a short code. Enter it in the browser to confirm.
-
The browser is now paired. It gets its own secret, and it needs that secret for every request.
- The code comes from the desktop app. The page your browser shows is the signed code that ships inside the desktop app, not code loaded from the web at that moment. An update to the desktop app updates it.
- Only this computer can reach it. Other computers cannot use the link, and neither can a browser that is not paired.
- Until a browser is paired, the desktop app’s page shows none of your data.
- Settings → Devices lists every paired browser. Remove unpairs one. Pairing and removing a browser are changes only you can make.
- Chrome first. Chrome and the browsers built on it come first. Safari and Firefox are tested too.
Private things need a fresh unlock
A linked browser shows your everyday data at once. Three kinds of things need a fresh unlock first: locked files, end-to-end encrypted collections and Hidden entries. You unlock with Face ID, a fingerprint, Windows Hello or your computer password.
Example: Workouts opens at once in Chrome. Your Diary is set to No AI, so it is locked, and Chrome does not show it. In Chrome, open Settings → Devices and click Unlock. Windows Hello pops up on the computer. Then Chrome shows Diary for 15 minutes, or until you click Lock.
- What counts as locked: a collection or entry that is Hidden, or whose AI choice is anything but Any AI (No AI, Only my local AI, Ask me first). These are the same items the app keeps in its encrypted locked file.
- Until the unlock, locked entries and collections are left out of everything the browser gets: lists, search, totals and counts, history, the live changes and the AI’s answers. A change or an undo that touches one is refused.
- On Linux the computer password is asked instead (through the system’s own password box).
- A Mac has no fresh unlock yet, so locked items stay out of the browser there.
When the desktop app is closed
The browser shows one button: Open the desktop app. It never falls back to a copy of its own, so your computer never holds a second copy.
The desktop app can start with your computer and sit in the tray (the menu bar on a Mac). Then it is usually running, and the browser works at once.
Not a separate device
A linked browser is part of the desktop app’s device. It is not a device of its own.
- The desktop app does the syncing with Cloud Sync, for the app and the browser.
- On Free, Cloud Sync covers one device. The desktop app and the browser on the same computer are that one device.
- On a computer without the desktop app, the browser is a device of its own, with its own copy. See Offline, and clearing your browser.
Only the desktop app writes
The desktop app is the only program that writes the database and the folder. The browser asks the desktop app to save, and the desktop app checks and saves the change. One writer means two programs never change the same file at the same time.
What a linked browser keeps
| In a linked browser | |
|---|---|
| Your data | Nothing. It uses the desktop app’s database. |
| Your files | Nothing. It shows them from your computer. |
| What is on screen | In memory, while the tab is open |
| Clearing the browser’s data | Loses nothing |
Want a folder? Install the desktop app
The ~/Kaizendex folder belongs to the desktop app. A browser never picks or writes a folder
of its own. A browser on a computer without the desktop app keeps its data in browser storage,
and can export everything as a ZIP. Restore from my folder is in the desktop app.
The desktop app is also the only place where you can turn Cloud Sync off. A browser on its own always uses Cloud Sync, because it can lose its data when it is cleared. See Cloud Sync.