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 a native Go app on MyGo and frostui, with live preview. It is a sibling of Frostmail.
  • The web app is a React UI with a CodeMirror 6 editor, 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.5.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 system extension can trail the latest release. The catalog lists the version it ships.

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.

Release v0.3.1 fixes two cases. In sync, a conflict version now reaches the hub when a delete from the hub applies first. In Settings, Background no longer shows an older answer from the desktop over a newer one. v0.3.1 also adds a database migration, so v0.3.0 cannot open the database after v0.3.1 has run.

Release v0.3.2 fixes sync after notesd stops in the middle of a change. If notesd stopped while it applied a change from the hub, it pushed that change back as its own after the restart. That could undo a later change from another device, for example delete again a file that another device brought back. Now notesd records each change before it applies it, and settles the record before the next sync. v0.3.2 also adds a database migration, so v0.3.1 cannot open the database after v0.3.2 has run.

Release v0.4.0 adds a Tasks pane. It lists the vault’s open tasks, the list items that start with [ ], grouped by note. Select a task to open its note at that line. Agents get the MCP tool list_tasks. The app’s details in the Flatpak remote now show 4 screenshots.

Release v0.5.0 replaces the desktop app with a native Go app. Your notes, vaults, and sync stay. The first start of v0.5.0 opens the default layout: the open tabs and the app’s preferences from v0.4.0 do not carry over. The native app draws math, plays audio and video in the vault, toggles a task in the reading view with undo, and follows block links. Its Settings have no Spellcheck control. notesd and the app also write their panics and a few coded errors to the local systemd journal, and send nothing over the network. To see them, run journalctl MESSAGE_ID=8915bdd215c84cbab0c31c05a1a33e7e.

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

The Flatpak does not read the data of a notesd that ran on the host, from a build or the .deb. To move, follow Moving from a host notesd: the order of the steps matters, and the Flatpak joins the hub as a new device.

If notesd does not start

Section titled “If notesd does not start”

If notesd does not start, the window shows the connecting screen. Press Details to see why: the last line of notesd.log, or, when the Flatpak portal did not start notesd, the checks to run. It also shows the path of notesd.log.

If the Flatpak portal did not start notesd, Details names 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, notesctl, and the desktop app build from source with Go. The desktop app needs GTK 3, Pango, and cairo when it runs. See Development.

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

Privacy