Firn

Firn installs snosi bootc OCI images from a declarative TOML recipe, with a terminal wizard and a graphical installer. It is for anyone who puts a snosi image on a disk: the wizards write the recipe, and the same recipe installs headlessly.

Firn is a GPL-3.0-only rewrite of fisherman, and it keeps the attribution of the code it draws from (NOTICE, ADR-0003).

Status: pre-release. It ships on the snosi installer ISO.

Documentation: docs/README.md

What it does

• Bootc-only installer. family = "bootc" installs an OCI image straight from a container registry, deployed from the RAM installer over containers-storage (ADR-0012).
• Recipe-driven. One versioned TOML file describes the target disk, image, security options and system configuration (schema, ADR-0005). Validation is fail-closed: unknown fields, unknown enum values and wrong-family fields are errors. Version 2 is current; bootc version 1 is accepted with a deprecation warning until 2026-12-30 and rejected from that date.
• Security options. LUKS root with a passphrase or TPM2 auto-unlock, and UEFI Secure Boot with MOK enrollment via secure-install schema-1 (ADR-0014).
• Terminal wizard. The bare firn command walks the install in one binary on the Charm stack (ADR-0007) and emits a recipe you can reproduce headlessly.
• Graphical installer. firn-gui is a windowed wizard with a keyboard shortcut for every action, from the nested module gui/ (ADR-0021).
• Install-time flatpaks. Flatpaks are installed into the target at install time, from the installer medium first and the network second; each image publishes its core set in an OCI label (ADR-0006, label spec).
• One progress protocol. Every user-visible signal is a typed progress event, and --json-progress streams it as NDJSON for automation (spec).

Install

The snosi installer ISO runs firn: its console boot entry opens the terminal wizard, and its graphical boot entry opens firn-gui (frostyard/snosi).

On Debian trixie with the Frostyard APT repository (https://repository.frostyard.org/debian/):

sudo apt install frostyard-firn

frostyard-firn-gui is for installer media, not installed systems.

Release and distribution lists the packages and where they go.

Use

firn                                                  # the terminal wizard
firn validate recipe.toml                             # check a recipe against this machine
firn install --confirm /dev/nvme0n1 recipe.toml       # install; --confirm must equal [target].disk
firn install --dry-run recipe.toml                    # preflight only, no disks touched
firn install --json-progress --confirm /dev/nvme0n1 recipe.toml   # NDJSON progress

The command-line surface explains the confirmation, dry-run and detection flags of both commands, and the recipe schema describes the file.

Develop

Firn is one Go binary with no CGO, plus the nested gui/ module. Everything below runs on the pins in mise.toml:

mise install   # Go, golangci-lint and Node, pinned and verified
make ci        # the credential-free gate that CI runs
make gui-check # the gui/ module's own gate

make gui-check needs Pango and Cairo installed: without them the text engine falls back to a stub that draws nothing and the tests pass without real layout. AGENTS.md holds the rules, and the architecture shows how the parts fit.

Where to go next

• AGENTS.md: the rules for agents and contributors.
• docs/README.md: the decisions, designs, specs and plans.
• SECURITY.md: the support policy, and how to report a vulnerability privately.
• LICENSE: GPL-3.0-only.
• NOTICE: the projects firn derives from.