Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Install with FORGE

FORGE is the InterGenOS installer. It takes you from the live environment to a deployed, bootable, user-configured system on a target disk. Every install runs through a verification gate that checks the cryptographic integrity of each package against the signed release manifest before any disk write occurs, so the system you boot is the system that was actually published.

This section covers what to expect during installation, how the installer is structured, and the device- and security-specific notes that matter once you commit to writing a disk.

What FORGE installs

FORGE deploys InterGenOS 1.0-dev (build id v1.0-dev1). The shipped desktop is GNOME 49 on Wayland. The installer also lays down the components that make the system trustable end to end:

  • pkm, the transparent package manager.
  • A signed boot chain (shim → GRUB → UKI) with a per-machine Machine Owner Key (MOK) generated during install. Secure Boot enforcement is optional and off by default on the current fleet; the signatures are present and ready for hardware where you turn it on.
  • dm-verity integrity sealing the live ISO image. (The installed root is an ordinary ext4 filesystem, verified per-file by pkm.)
  • UKI signing for the boot image.
  • InterGen, the tiered, hardware-detected, offline-first local assistant (Qwen models, zero telemetry), which includes a built-in security scanner, InterGen Sentinel (default Local-Rules plus Local-Qwen, with opt-in cloud providers).

Packages are organized into six tiers (toolchain, core, base, desktop, ai, and extra). The total count drifts as the distribution evolves; derive the live figure from the release manifest rather than treating any single number as fixed. As of 2026-06-15 the installable set is roughly 857 packages across those tiers.

How FORGE works

FORGE uses a split frontend/backend architecture joined by a declarative state model. A frontend collects your choices and emits a serialized YAML description of the system you want. The backend consumes that YAML and the credentials you supply, then executes the install.

Two frontends are available, and both drive the same backend identically:

  • GUI — a GTK4 / libadwaita wizard with a multi-screen flow (welcome, keyboard and locale, disk, user, packages, confirm, progress, done). Use this for a standard desktop install.
  • TUI — a dialog-based text interface suited to SSH sessions, headless servers, or keyboard-only navigation.

The backend runs a linear, phased pipeline. The first phase after configuration validation is the integrity gate: FORGE computes the SHA-256 of every package archive it intends to deploy and verifies it against the signed archive manifest. A mismatch halts the install before partitioning begins, unless you provide explicit, typed confirmation to override. That override phrase must be typed in full; the installer disables paste, drag-and-drop, and the right-click menu on the field so the consent is deliberate.

If a phase fails, FORGE halts the pipeline, performs best-effort unmounts scoped to how far the install progressed, and surfaces the exact point of failure on the final screen. Non-fatal warnings, such as a trust-chain audit-log copy failure, are reported there too so you always know the true state of the deployment.

Security posture

The install path is built so the result is a machine you understand, can modify, and can trust: the integrity gate proves what was written, the on-machine MOK keeps the boot chain under your control, the signed UKI protects the boot path (enforced once you enable Secure Boot), and pkm’s per-file hashes let you verify the installed system at any time.

In this section

If you run into trouble during or after install, see the Troubleshooting section and the FAQ.