FORGE(1)

NAME
forge - InterGenOS system installer (GUI or declarative-builder TUI)

SYNOPSIS
forge --archives DIR [--mode gui|tui|live] [--packages DIR] [--dry-run]

DESCRIPTION
forge is the InterGenOS system installer. It is invoked from the live ISO's GRUB menu (entries Install (Graphical) and Install (TUI Builder)) or from the Install InterGenOS launcher icon on the live GNOME desktop.

Forge runs in three modes, dispatched by the igos.installer= parameter on the kernel command line (set by the GRUB menu) or by an explicit --mode flag.

MODES

gui A GTK4 / libadwaita graphical installer with seven screens: Welcome —> Keyboard / Locale / Timezone —> Disk —> User —> Confirm —> Progress —> Done. The order matches the modal pattern of other distros (locale up front, the destructive disk decision before the user account, then final confirm + progress + done). Default mode when launched from a Wayland session.

tui A declarative-builder TUI on tty1. The TUI is not a text-mode version of the GUI — it is a builder. The user is walked through a small set of yaml-bound questions (locale, timezone, hostname, optional package toggles) via dialog(1), the answers are emitted to /var/lib/forge/install.yaml, and the install then runs non-interactively from that yaml. The disk choice and root + user passwords are not written to yaml — they are prompted for inline during the install proper. Pre-seeding the disk would be a fat-finger risk; pre-seeding a password would be a supply-chain risk.

live
    No install is dispatched. This mode is reached when no igos.installer= parameter is on the kernel cmdline; the live GNOME session shows a desktop launcher that re-invokes forge in gui mode when the user explicitly clicks it.

OPTIONS

--archives DIR
    Required. Path to the directory of .igos.tar.gz package archives produced by the InterGenOS build pipeline (typically /var/lib/igos/archives on the live ISO).

--mode {gui|tui|live}
    Force a specific frontend, overriding the igos.installer= kernel cmdline parameter and the session-type heuristic. Useful for testing the GUI from a tty1 session or vice versa.

--packages DIR
    Path to the packages/ directory in the InterGenOS source tree, used by the post-install hook runner and for tier-to-package mapping. Optional; if omitted, all archives in --archives are installed without tier filtering.

--dry-run
    Log all destructive commands (partitioning, package install, account creation, bootloader install) without executing them. The walking sequence and yaml emit still run; only the destructive steps are skipped.

--version
    Print forge version and exit.

--help
    Print usage and exit.

MODE SELECTION
When --mode is not supplied, forge resolves the effective mode in the following priority:

1.  igos.installer= on /proc/cmdline (set by the GRUB menu entry the user selected at boot).

2.  WAYLAND_DISPLAY in the environment, or XDG_SESSION_TYPE=wayland — both indicate a graphical session and resolve to gui.

3.  Fallback: tui on a console without a graphical session.

TUI WALKING SEQUENCE
The TUI walking sequence asks for four pieces of information in order:

1.  Locale — a glibc locale (e.g. en_US.UTF-8). A short list of common locales is presented; "other" lets the user type a custom value.

2.  Timezone — an IANA timezone (e.g. America/Chicago). A short list of common zones is presented; "other" lets the user type a custom value.

3.  Hostname — the machine name (default intergenos).

4.  Package groups — a checklist of high-level package groups (core, base, desktop-gnome, extra, ai). core is required and is force-included even if the user un-toggles it.

The walking sequence emits /var/lib/forge/install.yaml on completion. Disk and password collection happens immediately after, in a separate phase that is not written to yaml.

INSTALL CONFIG SCHEMA
The yaml emitted by the walking phase has the following schema:

    version: 1
    locale: "en_US.UTF-8"
    timezone: "America/Chicago"
    hostname: "intergenos"
    package_groups:
      - core
      - base
      - desktop-gnome

The yaml lives on the live overlay at /var/lib/forge/install.yaml and is not persisted to the installed target.

ENVIRONMENT

WAYLAND_DISPLAY
    If set, the session-type heuristic resolves to gui.

XDG_SESSION_TYPE
    If set to wayland, the session-type heuristic resolves to gui.

FILES

/var/lib/forge/install.yaml
    Ephemeral yaml config emitted by the TUI walking phase; consumed by the declarative-install runner.

/var/lib/igos/archives
    Default archive directory on the live ISO.

/mnt/target
    Mountpoint where the target root is assembled before the bootloader install.

EXIT STATUS

0   Install completed successfully (or --dry-run exit).

1   User cancelled during the walking phase or the disk/password prompt phase.

2   --archives directory not found, or unknown --mode value, or running as non-root.

EXAMPLES

Auto-detect mode from the GRUB cmdline:
    forge --archives /var/lib/igos/archives

Force the TUI builder (e.g. for testing from a graphical session):
    forge --mode tui --archives /var/lib/igos/archives

Dry-run the GUI install path against a custom archive directory:
    forge --mode gui --archives ~/build/archives --dry-run

SECURITY
forge must run as root. The installer collects the root and user passwords interactively (tui) or via Gtk.PasswordEntry (gui) and never echoes them. Passwords are passed to chpasswd(8) via stdin, never via command-line arguments.

On EFI systems the user is also asked for a one-time MOK enrollment password. This password is staged with the InterGenOS Machine Owner Key keypair and prompted for once, in MokManager, on the first reboot after install. After enrollment the password is no longer required.

The TUI walking sequence's yaml is intentionally narrow: it carries locale, timezone, hostname, and package groups only. Disks and passwords are collected interactively at install time so a stray or adversarial yaml cannot pre-seed a destructive disk choice or a known password.

SEE ALSO
pkm(1), chpasswd(8), dialog(1), systemd-stub(8), mokutil(1), sbsign(1)

docs/research/installer/iso-implementation-plan-2026-05-05.md — authoritative plan for the 3-part Secure Boot ISO of which forge is Phase 4.

intergenos-first-boot(7) — the first-boot password greeter that runs on the installed system.

AUTHORS
The InterGenOS maintainers.