Skip to content

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.

On your computer, the browser shows the page that the desktop app serves. You add the entry Hello world to the collection Super private in the browser. The browser holds only what is on screen. Over the link, which works offline, the desktop app saves the entry in its database, and the file Hello world.md appears in ~/Kaizendex/Collections/Super private within seconds. Super private is set to This device only, so it never goes to Cloud Sync. When the desktop app is closed, the browser shows one button: Open the desktop app.Your computerBrowser: the desktop app’s pageYou add the entry Hello world to Super privateit holds only what is on screen, in memorythe link, offline tooDesktop appsaves it; the only writer of the database and the folderDatabaseHello worldsaved at oncein your folder’s .kaizendex~/KaizendexCollections/Super private/Hello world.mdappears within secondsCloud SyncSuper private isThis device only:it never goes hereApp closed?the browser showsone button:Open the desktop app
One computer, one copy. The browser asks, and the desktop app saves.

What works today

The link is built. Before the web app is online, you open it at a local address.

  1. Start the desktop app.

  2. In Chrome, open http://kaizendex.localhost:47321. The page asks for a code.

  3. In the desktop app’s tray menu, click Pair a browser. The desktop app shows a 6-digit code. It works for 5 minutes.

  4. 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 name kaizendex.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.json in 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••••••••••••••••4cc6 and “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 ~/Kaizendex folder.
  • 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

  1. In Chrome, you make a collection, “Super private”. You set its Where setting to This device only.

  2. You add an entry to it: “Hello world”.

  3. The browser passes the entry to the desktop app. The desktop app saves it in its database, on your computer.

  4. Within seconds, the file ~/Kaizendex/Collections/Super private/Hello world.md appears.

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

  1. Open app.kaizendex.com in 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.

  2. The browser opens the desktop app’s own page, at a local address on this computer.

  3. The desktop app shows a short code. Enter it in the browser to confirm.

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