notekprdocs

Your own tools

The desktop app

notekpr in a window of its own on your computer, in the tray, starting at login, with a Markdown folder.

notekpr for your computer: the app you know from the browser, in a window of its own, that keeps running in the background, sits in the tray, can start when you log in, and keeps your notes as a folder of Markdown files too. For Linux and Windows (install it).

It is a client of your notekpr server like the browser and the CLI: your notes are encrypted on your computer before anything leaves it. Or it keeps your notes only on this computer, with no server and no account.

What it does

  • The app, in its own window. Everything the web app does: writing, drawings, sharing, comments, settings. Its files ship inside the app, so what runs on your computer is the version you installed.
  • In the background. Closing the window hides it in the tray (Close to the tray, on by default): your notes keep syncing and the window opens again at once. Quit notekpr in the tray's menu quits. Starting notekpr again while it runs shows its window.
  • Start at login. Start notekpr when you log in starts it in the tray, without a window.
  • A Markdown folder. Your vaults as a folder of ordinary Markdown files, synced both ways while the app runs, for Obsidian, VS Code, Neovim or any other editor (more in Your own editor).
  • Without the server. Like a browser, it keeps an encrypted copy of your vaults so it opens at once, but it asks the server for the keys each time it starts. Settings → Devices → Keep this computer usable offline keeps the keys too, so it opens and edits your notes when the server can't be reached (what that means). The Markdown folder works offline either way.

You don't need the CLI for any of that. It is still the tool for AI agents (its gateway), scripts, and computers without a screen.

Install it

From 0.17.0 on, each release on GitHub carries the app for Linux: as packages (amd64 and arm64) for systems with glibc 2.35 and WebKitGTK 4.1 or newer, and as a Flatpak (x86_64) for any Linux. From 0.20.0 on, an installer for Windows too:

SystemInstall
Windows 10, 11the release's installer, notekpr-desktop_<version>_windows_amd64_setup.exe (x64; Windows 11 on ARM runs it too): for you only, without administrator rights (below)
Any Linuxthe release's Flatpak, notekpr-desktop_<version>_x86_64.flatpak: flatpak install --user ./notekpr-desktop_<version>_x86_64.flatpak (it brings GNOME's runtime from Flathub; it doesn't update itself yet: install a newer release's the same way; below)
Archfrom the AUR: notekpr-desktop-bin
Debian 12+, Ubuntu 22.04+, Mint 21+the release's .deb: sudo apt install ./notekpr-desktop_<version>_amd64.deb (arm64 on ARM)
Fedorafrom COPR: sudo dnf copr enable coolapso/notekpr, then sudo dnf install notekpr-desktop; or the release's .rpm: sudo dnf install ./notekpr-desktop-<version>-1.x86_64.rpm (aarch64 on ARM)
Other Linuxthe release's notekpr-desktop_<version>_linux_<arch>.tar.gz (the app, its desktop entry and icons; it needs WebKitGTK 4.1 and libayatana-appindicator installed), or build it from source

It shows in your applications as notekpr. COPR's package updates with the rest of Fedora; the release's .deb doesn't update itself (no package repository yet): install a newer release's the same way. The packages bring what the app needs from your system's own: WebKitGTK, the tray's library (libayatana-appindicator) and xdg-utils. The CLI is a package of its own (notekpr-cli, cli.md), and you don't need it for the app.

On Windows

The installer puts notekpr in your Start menu. The app's window is drawn by Microsoft Edge WebView2 Runtime, which Windows 11 and most Windows 10 computers have; where it's missing, the installer downloads it from Microsoft and installs it. The installer isn't signed yet, so Windows may say it protected your PC: More info, then Run anyway.

To update, run a newer release's installer: a running app quits first (and if a copy for another profile still runs, the installer asks you to quit it), and your settings stay. To remove the app: Settings → Apps → Installed apps → notekpr → Uninstall. That removes the program, its Start menu entry and its starting at login; your settings and data (below) and your Markdown folder stay. The installer and the uninstaller also run silently with /S.

Getting started

  1. Where your notes are. The first time, the app asks where you keep your notes. On a notekpr server: its address — the one you open in a browser, like https://notes.example.com. The app checks the server and starts again with it. The server must be recent enough for the app (the app says so if not). Or Only on this computer: no server and no account (below); then there is no step 2.

  2. Sign in. Continue with … opens your browser at your server's sign-in page; sign in there as always (passkeys and your password manager work). Then your server asks whether to sign the app in, with a code: Continue only if it is the code the app shows (a sign-in you didn't start shows another, or none). The browser sends you back to the app; you can close that tab then.

  3. This computer. As for any new device: on your first device the app makes your keys and shows your recovery key; otherwise approve it from a device you already use, or unlock it with your recovery key (Your other devices).

  4. Set it up. Before your notes open, the app asks what you want of it on this computer, as notekpr setup does for the CLI:

    • Your notes as Markdown files too, for other editors and AI agents: a folder to keep them in (below), or not now. A folder that holds notes already (an Obsidian vault, say) can have them brought in. If the CLI keeps a Markdown folder for this account already, the app offers to take it over.
    • In the background: whether to start notekpr when you log in, and to close it to the tray. Asked the first time only: these are the app's, not an account's.

    Each account is asked once, the first time it opens (accounts added before there was this step too). Settings → Desktop app → Set it up again… asks again.

Settings → Desktop app holds the app's own settings: the tray, starting at login, the Markdown folder and your accounts.

Accounts

The app can have several accounts: one on each server you use it with, and one only on this computer. Click your name in the sidebar: Accounts lists them, the open one ticked. Pick another to switch: the app starts again on it, in a moment. Add an account… adds a server (the app asks first, in a window of the system's) or Only on this computer. Settings → Desktop app → Accounts has the same list.

  • Each keeps its own: its sign-in, this computer's keys for it, the encrypted copies of its vaults, its unsent changes and its Markdown folder. Switching back finds them as they were, still signed in. Nothing of one account reaches another, and only the open one syncs (its Markdown folder too).
  • Removing an account (Remove, beside any but the open one and On this computer; the app asks first) only takes it off the list: what the app keeps for it stays, and adding it again finds it all. To delete that from this computer, open the account and use Forget this computer.
  • A server that can't be reached (down, moved, its address mistyped, or no network): the app says which address it tried, and offers Try again, your other accounts and adding one. It never moves to another server by itself.

To take notes from one account to another: export them in one (Settings → Account → Data), switch, and import them in the other.

Only on this computer

No server, no account to make: the app keeps your notes on this computer only. It runs notekpr's server inside itself while it runs, on this computer only, and signs itself in to it: there is nothing to sign in to, and nothing else gets in. Everything works as with a server — vaults, quick notes, drawings, comments, history, attachments, search, the Markdown folder — and is stored encrypted as on any server. The first time, the app makes your keys and shows your recovery key, as on a server: keep it, it opens your notes again if the app loses what it keeps for its window.

What needs a server: your other devices (another computer, your phone, a browser), sharing vaults or notes with other people, invitations, and AI agents with vaults of their own (an assistant can work with the Markdown folder instead). Where they'd be, the app says they need a server. Signing out and the list of sessions aren't there either: your account on this computer is what guards your notes.

Your notes exist only on this computer, so keep a copy: a Markdown folder (every note as a file, which your backups copy), or an export now and then (Settings → Account → Data: your vaults and quick notes as Markdown files in a .zip; imported, they become new vaults, without their history or comments).

It is one of your accounts: switch between it and your servers' from the list. To move your notes to a server, export them here, add the server's account, sign in and import the export there.

The Markdown folder

Settings → Desktop app → Markdown folder → Choose a folder… (or the setup) and pick a folder: an empty one, one notekpr kept before, or one that holds notes already (below). The app asks you, in a window of the system's, to confirm that it may write your notes there decrypted — any program you run can read them, and backup or cloud tools may copy them. Then each vault becomes a folder in it, and:

  • changes you make to the files (with any editor) reach your notes and everyone in the vault within moments; changes from others are written into the files;
  • it keeps going while the window is closed to the tray, and after the app starts again;
  • it works offline: changes wait until the server can be reached.

How changes made at the same time are merged, renames, deletes and conflicts: the same as the CLI's folder (cli.md §4–7), since it is the same code.

Stop… stops it: the files stay where they are, and the app forgets its own copies for the folder. The folder follows the same rules as the CLI's: a folder the CLI already keeps in sync (unless the app takes it over) or one in or around it, one inside notekpr's own data or your home folder itself is refused — and the CLI refuses the app's folder in turn. A hidden file at the folder's top, .notekpr-folder, says which notekpr keeps it, so every copy of notekpr on the computer sees that, wherever it keeps its settings (cli.md, "One keeper per folder").

Each account has a Markdown folder of its own (two can't share one): only the open account's is kept in sync, and switching back to an account resumes its folder without asking.

The folder uses this computer's device and the window's sign-in: signing out stops it (signing in again resumes it), and Forget this computer asks whether to forget its keys and copies too (never the files). If this computer is removed from your devices elsewhere, the folder stops; Stop… then forgets what it kept.

Exports and attachments you download land in your Downloads folder, under a name of their own (never over another file).

Notes already in the folder

A folder that holds notes of its own (an Obsidian vault, say) is offered what notekpr setup offers:

  1. Move them into a vault there. Everything in the folder, hidden files too (.obsidian, .git), moves as it is into a folder of its own, <folder>/<vault>/: renamed, nothing copied or rewritten. From then on it syncs. In Obsidian, open <folder>/<vault> as the vault: its settings came along. Close Obsidian and other apps using the folder first.
  2. Copy them into a vault in another folder, which you choose next: that becomes the Markdown folder, and the first stays as it is.
  3. Choose another folder.

The vault is one of yours by the name you give (the notes join what it has; others who share that vault see them too) or a new one, My notes unless you name another. The app's window of the system's says what moves or is copied where, and into which vault, before anything changes. The first sync takes the notes in exactly as they were, as the CLI does (Coming from Obsidian). A folder that holds other files but no notes is used as it is: those files stay, not synced.

From the CLI

If the CLI keeps a Markdown folder in sync for the same account on the same server, the setup and Settings → Desktop app offer to take it over: Take over ~/Notes from the CLI. After your yes in a window of the system's, the app:

  1. stops the CLI's background sync, notekpr-sync@<profile>, and turns it off at login (Linux; elsewhere the CLI has none). The Flatpak can't: it shows the command to run instead (systemctl --user disable --now notekpr-sync@<profile>) and goes on once the CLI's sync has stopped — as for a notekpr sync you started yourself (stop it with Ctrl-C);
  2. makes the CLI forget the folder, as notekpr sync --no-dir does. The CLI stays signed in: its commands and its gateway still work, without the folder;
  3. keeps the folder in sync itself, from where the CLI left it: the vaults' folders and everything else in it stay as they are.

A file changed in the moment between the CLI stopping and the app taking over is taken in as on any first sync: kept beside its note as a conflict copy when the two differ. To hand the folder back: Stop… here, then notekpr sync --dir ~/Notes and systemctl --user enable --now notekpr-sync@<profile>.

The tray

Windows shows the app's icon in the notification area (the arrow beside the clock keeps it, unless you drag it out). Most Linux desktops show tray icons (KDE, Cinnamon, Xfce, sway or Hyprland with a bar that has a tray). GNOME needs the AppIndicator and KStatusNotifierItem Support extension. Without a tray, closing the window quits the app, and Close to the tray says so.

The tray's menu: Open notekpr, Open the Markdown folder, Settings and Quit notekpr.

Where it keeps things

WhatWhere (Linux)
Its settings (the tray, the account open) and its accounts~/.config/notekpr-desktop/default/settings.json, accounts.json
The window's data (this device's key, encrypted copies of your vaults), one folder per account (this-computer for notes only on this computer)~/.local/share/notekpr-desktop/default/webview/
Only on this computer: the server's data (its database and attachments, encrypted as on any server)~/.local/share/notekpr-desktop/default/this-computer/
The Markdown folders' keys and encrypted copies, one folder per account~/.local/share/notekpr-desktop/default/folders/
Starting at login~/.config/autostart/notekpr.desktop

On Windows the same folders are under %APPDATA%\notekpr-desktop (in place of ~/.config/notekpr-desktop) and %LOCALAPPDATA%\notekpr-desktop (in place of ~/.local/share/notekpr-desktop); starting at login is the value notekpr in the registry's HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run.

What is protected how: security.md. NOTEKPR_DESKTOP_CONFIG_DIR and NOTEKPR_DESKTOP_DATA_DIR replace ~/.config/notekpr-desktop and ~/.local/share/notekpr-desktop, as do --config-dir and --data-dir. A copy of the app with folders of its own runs beside the installed one, and starts at login with an entry of its own (notekpr (development …), with those folders): development runs (task desktop) keep theirs in the repository's data/ (development.md). Other copies of notekpr on the computer don't see such a copy's Markdown folders. NOTEKPR_LOG=debug shows more of what it does (on standard error).

Several people side by side (development, testing): notekpr-desktop --profile bob keeps its own settings, sign-in, data and folder, like the CLI's --profile.

notekpr-desktop --quit (with the same --profile) has the running app quit, as Quit notekpr in its tray does: it stops its Markdown folder's sync first. With none running it does nothing. The Windows installer uses it before it replaces the app.

The Flatpak

The Flatpak keeps the same things under ~/.var/app/md.notekpr.Notekpr/ (config/notekpr-desktop/…, data/notekpr-desktop/…), and works the same, with these differences:

  • It may read and write your home folder, so that the Markdown folder can be anywhere in it you choose (and downloads land in Downloads); not the rest of the system.
  • Start notekpr when you log in asks your system, which may ask you once whether notekpr may run in the background. Not every desktop can (GNOME and KDE can; Hyprland, for one, can't): the app then says so.
  • The CLI and the app still refuse each other's Markdown folders, whichever way each is installed: each looks for the other in both places.

Build it

To build it yourself, or to work on it: the app is crates/desktop (Tauri 2 around the web client, crates/web). It needs what the web client needs (development.md), plus WebKitGTK 4.1 and GTK 3 with their headers, and libayatana-appindicator for the tray:

SystemPackages
Archwebkit2gtk-4.1 libayatana-appindicator
Debian, Ubuntulibwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev
task build:desktop       # target/release/notekpr-desktop, the optimized web client inside
task desktop             # run it (unoptimized web client), e.g. against `task dev`

The app's files are taken from the folder TAURI_CONFIG names ({"build":{"frontendDist":"…"}}); without it, a build has a placeholder page instead (what task test and task lint build).