Skip to content
Frostyard docs

frostread

frostread is a feed reader and a read-later list that only your tailnet can reach. It runs behind lodge, where lodge shows it as the app Read. You need it if you run lodge and want to follow feeds and keep articles to read later.

  • Sources: RSS, Atom, and JSON Feed, imported and exported as OPML. Each source polls about every 20 minutes.
  • Read later: save a link from the app, with readctl save, or from an agent with a read;write token.
  • From your phone: a bookmarklet opens a save page. It saves only when you tap Save.
  • Articles are extracted and sanitized, and their images are inlined, so the browser loads nothing remote.
  • Unread, starred, and archived views, and full-text search.
  • Save an article as a note under Reading/ in Frostnotes.
  • Agents, such as Porter, reach it at /mcp/read.

Status

Section titled “Status”

frostread is pre-release. The latest release is v0.1.0. Each release attaches one package, frostyard-readd_X.Y.Z_amd64.deb, for lodge’s host. On a Frostyard image, the readd system extension installs it. The daemon, its API, readctl, MCP, save-as-note, the web app, save from the phone, and the blob sweep are built.

A desktop app is planned: the Flatpak org.frostyard.Frostread, with its own readd, local by default. How it works with lodge is not decided yet. Nothing is built. Today frostread runs only behind lodge.

Install

Section titled “Install”

frostread runs as lodge’s read app, beside lodge and Notes, on lodge’s host. The web bundle builds in an nsl machine, and readd and readctl install to /usr/bin. To check a release .deb, run gh attestation verify frostyard-readd_X.Y.Z_amd64.deb --repo frostyard/frostread. The install steps in the README are the canonical ones.

Update and roll back

Section titled “Update and roll back”

On a Frostyard image, Updex updates and rolls back the readd system extension. Update, roll back, and remove has the steps, with the backup to take first. The release .deb is built for that extension, and it is not in the Frostyard APT repository.

On a host installed by hand from source, follow Update and Roll back in the README. The Update steps take a rollback archive before the new build goes in.

Documentation

Section titled “Documentation”
  • README: what frostread is and how it runs behind lodge.
  • Install on lodge’s host: the 6 install steps.
  • API spec: the API, readctl, the configuration, and the state layout.
  • Design overview: the parts and how they fit.
  • ADR-0008: the proposed design of the desktop Flatpak. Its lodge mode is still an open question.
  • ADR-0003: the fetcher reaches only public addresses.
  • ADR-0006: save from another page with a bookmarklet.
  • Roadmap: what is built and what comes next.

Limits

Section titled “Limits”
  • Read fetches only public addresses. A feed on your home network cannot be read.
  • frostread refuses a database with a newer schema than the program knows. Back up /var/lib/frostread before an update.

See also

Section titled “See also”

Sources

Section titled “Sources”

Reviewed 2026-10-28.