Skip to content
Frostyard docs

Frostyard documentation

Frostyard makes bootc images and /usr system extensions, built with snosi. These guides cover each Frostyard image, every extension in the catalog, the apps, and the tools. Each page lists its sources at the bottom.

Start here

Section titled “Start here”
SnowThe general-purpose GNOME desktop on a bootc/composefs image.
FloeThe headless server image for containers and services.
Install a Frostyard imageDownload Firn, check the ISO, and pick a disk.
Get softwareChoose Flatpak, Homebrew, a system extension, or Distrobox.
DockerAdd Docker Engine, containerd, Buildx, and Compose.
IncusRun system containers and virtual machines, with Incus's own QEMU.
TailscalePut the host on your tailnet.
System extension catalogSee every extension in the catalog, and enable or update one.
Manage extensionsFind, enable, check, update, and remove any extension.
UpdexManage system extensions: enable, update, and remove them.
APT repositoryThe package source of Frostyard images. Works on Debian 13, without support.
FrostmailA mail client with a daemon, a desktop app, and a CLI. Pre-release: build it from source. A Flatpak is coming.
FrostnotesMarkdown notes with sync, a desktop app, and MCP for agents. Pre-release: install it from the Frostyard Flatpak remote.
lodgeThe tailnet web shell that runs Frostyard's apps. Pre-release: build it from source.
frostreadA tailnet-only feed reader and read-later list, shown as Read in lodge. Pre-release: build it from source.
PorterAn assistant in lodge that reads your mail, notes, and feeds, and drafts but never sends. Pre-release: build it from source.
nslRun WSL-style Linux machines on a Frostyard image.
IglooOpen nsl machines from a GNOME terminal's New Tab menu.
ChairLiftStage system updates, update Homebrew and Flatpak apps, and toggle features.
intunemeRun Microsoft Intune for a managed work device in a container.

Choose an image

Section titled “Choose an image”

Each image has its own guide:

Product Role Page
Snow General-purpose GNOME desktop Snow
Snowfield GNOME desktop for Microsoft Surface devices Snowfield
Sundog KDE Plasma desktop, bootc only Sundog
Floe Headless server image Floe
Base Shared image foundation, not an installer choice Base

Snowfield is untested on representative Surface hardware. The installer offers the four bootc products; Base is not one of them. The snosi installation guide has the full table.

Install and first boot

Section titled “Install and first boot”

Install with Firn. It needs UEFI, erases the disk you pick, and asks you about each security choice. Start with Install a Frostyard image: it covers checking the ISO, the disk warning, first boot, and MOK enrollment.

Every image checks for updates hourly, stages a new version, and starts it at your next normal reboot. It never forces a reboot. Install, update, and roll back takes you from the download to a rollback.

Old nbc and native A/B installs got no new images or updates after 2026-09-30. They cannot convert in place: back up, install fresh, and restore. See Move from an nbc or A/B install.

How a Frostyard system is built

Section titled “How a Frostyard system is built”

A Frostyard system has three layers:

  1. The image. It holds the read-only /usr, the kernel, the desktop or server software, and the updater.
  2. Your state. /var holds homes, containers, and service data. /etc holds your configuration and carries it into each new version.
  3. System extensions. EROFS images that add to /usr only. They cannot write /etc or /var. An extension keeps its default configuration in /usr/share/factory/etc, and tmpfiles.d copies it into /etc at boot.

Every image carries a definition for each extension in the catalog, switched off. The extension itself is not in the image: you turn it on, and download it, with Updex. Each extension page has the steps. An enabled extension updates on its own: a new version is staged and starts at the next boot. See Automatic updates.

Each extension page shows the newest version the catalog listed at its last sync. Run updex features check to see what you can update to.

Not covered yet

Section titled “Not covered yet”

Snow’s first-setup app (snow-first-setup) and the hotedge and Logo Menu GNOME extensions have no guide of their own. The Snow page lists them.

Repogen, the generator for sysext and other package repositories, has no guide here. Read its README.

Sources

Section titled “Sources”