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

Package & Config Reference

This page is the reference for what InterGenOS ships and how to inspect it: the package tiers, the on-disk state that pkm records, and the commands that answer “what is installed, at what version, owning which files?” directly from the live system.

Because a hand-maintained package table drifts the moment a package is added, split, or superseded, this reference does not reproduce a frozen catalog of every package. Instead it tells you how the package set is structured and how to derive the authoritative, current answer from the machine in front of you.

Why the live system is the source of truth

A wiki table written once quietly falls out of step with the packages actually built, the versions actually shipped, and the files actually deployed. Once that happens the documentation stops being trustworthy, and a document you cannot trust is worse than no document.

InterGenOS treats documentation drift as a defect, not an inconvenience. The trustworthy reference is derived from the same sources that build the system — the package definitions and the recorded install state — so that what you read matches what is on disk. That is part of the wider posture of the distribution: a machine you understand, can modify, and can trust. You cannot trust a system you cannot accurately describe.

The two sources of truth are:

  • The package definitions. Each package is described by a definition under the package tree, grouped into build tiers.
  • The installed-state database. On a live system, pkm records every installed package, its version and tier, and every deployed file with its SHA-256 hash. See the package manager reference for the data model.

Reconciling these is what makes the reference trustworthy: the definitions say what should be built, and the database records what was installed.

What the reference covers

Per tier, the package set is described by:

  • Package name, version, and tier.
  • Short description.
  • Declared runtime dependencies.
  • Supersede relationships (which package replaces which), since InterGenOS upgrades packages by a supersede model rather than in-place replacement.
  • Tracked configuration files: the /etc/ entries that pkm manages specially to preserve user modifications.

See the package manager reference for supersede semantics and the configuration-file handling these fields are drawn from.

Build tiers

InterGenOS organizes packages into six tiers, built in order during the image build: toolchain, core, base, desktop, ai, and extra. The tier counts shift continuously as packages are added, split, or superseded, so any number printed in a wiki page is a snapshot rather than a contract.

Derive the live counts from the package tree or from pkm on a running system rather than treating a written number as permanent. For example, to count packages per tier from a checkout of the source tree:

for tier in toolchain core base desktop ai extra; do
  printf '%-12s %s\n' "$tier" "$(find packages/$tier -name package.yml | wc -l)"
done

The build itself runs as a sequence of phases. The package-building phases produce the tiered packages; the surrounding phases handle source verification, environment and chroot setup, kernel and bootloader, image assembly, manifest generation, squashfs, UKI/dm-verity, and ISO creation.

Querying the real system

The authoritative live answer comes from the package manager itself. pkm keeps a SQLite database at /var/lib/igos/pkm.db and human-readable text manifests under /var/lib/igos/packages/, so the installed state is both fast to query and directly inspectable. The text manifests can be read with ordinary tools, no database client required.

Common queries against the live state:

  • pkm list — list installed packages.
  • pkm info <package> — show a package’s version, tier, and details.
  • pkm files <package> — list the files a package deployed.
  • pkm provides <path> — find which package owns a file.
  • pkm depends <package> — show declared dependencies.
  • pkm verify — recompute the SHA-256 hash of every installed file and compare it against the recorded hash, detecting both corruption and unauthorized modification.

That same hash data is what describes deployed files. For the full data model, operations, and integrity behavior, see the package manager reference.

Notes on scope

This reference describes what the distribution ships today, not what is planned. The shipped desktop is GNOME 49 on Wayland. The shipped local assistant is InterGen, which includes a built-in security-scanner subsystem, InterGen Sentinel; InterGen and the llama.cpp inference engine are the two packages in the ai tier. Planned components, such as switchable desktops or additional application campaigns, are not part of the package tree until they are built, so they do not appear in the installed-state database until then.

This reference exists so that the packages and configuration on your machine can always be described accurately, and therefore audited.