Skip to content
Frostyard docs

Frostnotes

Frostnotes is a notes app in the spirit of Obsidian. Your notes are plain markdown files with YAML frontmatter, in a folder you own. You need it if you want notes that sync between your devices and that agents can read and write.

  • notesd is a Go daemon. It watches your files and keeps a SQLite index.
  • Each device syncs with a self-hosted hub. There are no conflict copies.
  • The desktop app is Tauri v2 with a CodeMirror 6 editor. It is a sibling of Frostmail.
  • The web app is the same UI, served by lodge. A narrow screen gets a phone layout.
  • Agents use MCP: notesctl mcp on your host, or lodge’s /mcp/notes with a scoped token.
  • Obsidian vaults open as they are.
  • Every write is kept as a version for 30 days.

Status

Section titled “Status”

Frostnotes is pre-release. The latest release is v0.3.0. Its Flatpak is in the Frostyard Flatpak remote. The release also attaches frostyard-notesd_X.Y.Z_amd64.deb, for lodge’s host. The .deb holds notesd, notesctl, the units, the frostnotes user, and the web build for lodge’s notes app. Frostnotes is not in the Frostyard APT repository or the Frostyard Homebrew tap. On a Frostyard image, the notesd system extension installs it.

The vault, sync, and the desktop app are done. Notes inside lodge is in progress: notesd runs as lodge’s notes app. The hub moved behind lodge on 2026-10-26, and devices now sync through lodge. Graph and queries (Obsidian Bases) are planned. A hub container image and systemd unit, and Frostyard APT packages, are planned. Windows and macOS builds, Canvas, and a mobile app come later.

Release v0.3.0 adds a hub join from the app, a background setting, and a new window that replaces an older notesd after an update. The window also says why notesd did not start. The join form, the background setting, and the update replacement are not yet tested on a real desktop.

Install

Section titled “Install”

The desktop app is a Flatpak. It works on its own: you need no account, server, lodge, Tailscale, or other app. It carries the UI, notesd, and notesctl. Floe has no Flatpak.

Add the Frostyard remote once, for your user:

flatpak remote-add --user --if-not-exists frostyard https://frostyard.github.io/flatpak-index/frostyard.flatpakrepo

Apps use runtimes from Flathub, such as the GNOME runtime. A --user install gets a missing runtime only from a user remote, so add Flathub for your user too:

flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

Install Frostnotes:

flatpak install --user frostyard org.frostyard.Frostnotes

The Frostyard Flatpak remote has the canonical steps.

Check the install:

flatpak info org.frostyard.Frostnotes

You see version 0.3.0. Frostnotes shows in the app grid. Update it with flatpak update. From v0.3.0, when you open a new window after flatpak update, the app replaces a notesd of an older build with the new one, and you need no logout. The update from v0.2.0 to v0.3.0 is different: the v0.2.0 notesd keeps running until you log out and in. Your notes, files, and versions stay.

Run the CLI on a desktop through the Flatpak, for example:

flatpak run --command=notesctl org.frostyard.Frostnotes vault list

notesd runs in its own sandbox. The first launch asks the Background portal to let it run in the background and start at login. With that permission, and with the app’s setting On (below), notesd keeps running after you close the last window, until you log out. If you turn Run in Background off (GNOME Settings, Apps, Frostnotes), the desktop stops notesd once no window is open: on GNOME 48, about 45 seconds after the last window closes. Sync then waits until you open the app again.

You can also set this in the app. Open Settings, then Background, then “Keep syncing when no window is open”. It is On by default. On: notesd keeps running after the last window closes, and it can start at login. Off: notesd stops when the last window closes and does not start at login, so notes from other devices arrive only while a window is open. With the desktop permission off, the desktop’s own stop wins. The setting applies to the installed app, for all vaults. The section shows only in the Flatpak.

The app’s data is under ~/.var/app/org.frostyard.Frostnotes/, and the notesd log is ~/.var/app/org.frostyard.Frostnotes/.local/state/frostnotes/notesd.log.

If notesd does not start

Section titled “If notesd does not start”

If notesd does not start, the window says why, under “Reconnecting to notesd…”. It shows the last line of notesd.log, or, when the Flatpak portal did not start notesd, the checks to run. It always shows the path of notesd.log.

If the Flatpak portal did not start notesd, the window lists these commands:

  • flatpak override --user --show org.frostyard.Frostnotes
  • flatpak override --user --reset org.frostyard.Frostnotes
  • systemctl --user status flatpak-portal.service

If you add or create a vault in a folder outside the Flatpak’s file access, the app refuses it and names the fix: flatpak override --user --filesystem=PATH org.frostyard.Frostnotes. Then log out and in.

Sync with a hub

Section titled “Sync with a hub”

Sync with a hub, for example the hub in lodge, is optional. Nothing turns it on for you.

  1. Open the vault menu, and press Manage vaults…. With no vault yet, the app opens there.
  2. Press Join on the row “Join a vault on a hub”.
  3. Fill in Hub URL, for example https://lodge.example.ts.net/device/notes, Hub vault name, This device’s name (optional), and Location.
  4. Press Join.

If this device has not paired with that hub before, the app shows a one-time code. Approve it on the hub’s machine with notesctl hub approve CODE. On lodge’s host, run sudo -u frostnotes notesctl hub approve CODE. The code expires in 10 minutes. The app then makes the vault, joins it, and opens it.

The canonical steps are in The hub behind lodge and Pairing and sessions.

To sync a vault you already have, open the vault, then Settings, Sync, Join….

Settings, Sync also has Pair again… for a hub that refused this device’s token. To leave a hub, open Settings, Sync. In the Stop syncing row, press Leave, then press Leave again to confirm. The vault’s files stay on your computer, and you can still edit them. The hub keeps its copy.

From the terminal, with your local vault’s name as VAULT:

flatpak run --command=notesctl org.frostyard.Frostnotes sync leave --vault VAULT

Build from source

Section titled “Build from source”

notesd and notesctl also build from source with Go. You build the app in an nsl machine. See Try it and Develop in the README.

Install the hub on lodge’s host

Section titled “Install the hub on lodge’s host”

A hub runs on lodge’s host as lodge’s notes app, as the system user frostnotes. To check the release .deb before you install it, run gh attestation verify frostyard-notesd_X.Y.Z_amd64.deb --repo frostyard/frostnotes. The hub steps are the canonical ones.

Documentation

Section titled “Documentation”

Limits

Section titled “Limits”
  • There is no graph view and no query view yet.
  • The desktop app builds for Linux only.
  • notesd indexes a note over 10 MB by name only.
  • notesd refuses a newer database. Back up ~/.var/app/org.frostyard.Frostnotes/ before you install a newer Flatpak. For a build from source, back up $XDG_DATA_HOME/frostnotes.

See also

Section titled “See also”

Sources

Section titled “Sources”

Reviewed 2026-10-30.