PengyOS / Docs / How it's put together

How PengyOS is put together

The design decisions behind the images, on one page: what's in the base, how software gets in, how the system is maintained, and what may be changed without a human signing first.

This is the short version. The authoritative record is the project's own design documents next to the source — a SPEC with every component decision and the alternatives it beat, a principles document, and use cases whose acceptance criteria become tests. Where this page and those disagree, they win, and they're all in the public repository: github.com/patw/pengyos.

What's in the base image

LayerDecisionWhy
Build engineBuildroot 2026.08, pinned, with our own BR2_EXTERNAL tree of boards, defconfigs and recipesthe keystone decision: it decides what "reproducible" can mean
KernelLinux 7.2, pinned, configured per hardware, not patchedlatest stable by policy; a configured kernel beats a forked one
BootGRUB (UEFI), one kernel per slot, switched through grubenv; Plymouth splash on the Desktopboring and proven. Slot switching without UKIs
Initsystemd, kept for the contract (unit semantics, targets)compatibility over novelty. Its interior can be replaced, its contract may not
StorageRead-only ext4 system in A/B slots, plus a btrfs data partition for everything that is this machine; /etc is an overlayan update swaps the system, never your files
Our codeRust for system components (the installer GUI, desktop pieces), Python for tooling, C upstreamthe right tool for each job
ProvenanceSPDX SBOM in every image, ed25519-signed release manifests. Secure Boot and measured boot are not enforced yettrust from verification, and no claim we can't back up

Where software comes from

Four lanes, layered by trust. Source recipes are the default: Buildroot builds the package from its tarball against our configuration. Upstream artifacts are used when a project ships binaries and no source build makes sense, pinned by hash. Flatpak and AppImage bring in sandboxed desktop applications — that's how Firefox, Spotify or Steam get on a PengyOS Desktop. Compatibility guest containers cover software that only exists as a .deb or .rpm, and they run in a container rather than in the system.

Proprietary pieces are the exception and they are visible: NVIDIA's driver lives in its own two images, device firmware ships in the base image, and each exception is written down with its reasoning. A machine that works beats a pure one, but the compromise gets named.

The maintenance loop

OBSERVE → PROPOSE → BUILD → VERIFY → RATIFY → (attest, log, repeat)
StepWhat happens
ObserveTrack upstream releases, changelogs and security advisories for the pinned component set, and triage each one: security, relevant, or ignore. This is the part a language model is genuinely good at — reading a great deal and judging relevance.
ProposeThe agent drafts the change (a version bump, a patch, a new component) with its justification and files it. It does not apply it.
BuildA reproducible build produces the artifact and its SBOM.
VerifyAn independent witness boots the image and runs the behaviour tests. The agent's own tests are necessary but not sufficient.
RatifyA person approves anything crossing the security boundary. Everything is logged and attested.

The loop runs nightly. It watches Buildroot, the kernel, COSMIC and NVIDIA tags, plus the NVD, CISA KEV and EPSS feeds, triages new CVE matches with a local model, batches the night's changes into one build, boot checks the result, and publishes it to the testing channel. It has no code path to stable: update-promote is not reachable from the loop, and promotion is a person's decision after the image has run on real hardware. The first release the loop shipped on its own was 26.10.8, on 2026-10-05.

What may change, and who signs it

TierSurfaceWho may change itHow
0 — BaseKernel, libraries, the image itselfnobody at runtimea signed image written to the other slot, booted once on trial, kept only if it reaches multi-user
1 — Machine/etc, services, driver config, users' datathe admin, or the agentlives on the data partition and is never touched by an update. Snapshots and a change journal are planned, not built yet
2 — CriticalSigning keys, the update trust root, privilege changesa human signsa small, enumerated list. The agent cannot change its own trust root

A fix applied on a live machine is supposed to end up in the build definition — a board fragment, an overlay file, a recipe — so the next image already has it. That's how the project avoids doing the same surgery twice.

How far down the stack we go

Every layer sits behind a stable interface, and the order of replacement matters: leaf userspace first, then the desktop and session, then the mid-stack, then init, then boot. Smallest blast radius, cheapest to verify, easiest to revert. Replace interiors, not interfaces.

The kernel stays, configured per hardware rather than rewritten. A from-scratch browser is a non-goal; the web platform grows faster than any implementation can follow. Forks are rationed: at most ten maintained forks, each with a named expiry condition, and today the count is zero. Creating one is a human decision, not something the nightly loop does.

The ten principles

PrincipleWhat it means in practice
Freedom firstMIT and Apache-2.0 preferred, LGPL when dynamically linked, GPL for standalone system components. Hardware-forced exceptions ship in plain sight with their reasoning.
Assemble, don't deriveCompatible with the Linux world, derived from no distro. No inherited configuration, patch sets or packaging decisions.
Compatibility is a contractPOSIX, ELF, systemd unit semantics, D-Bus, Wayland and freedesktop are honoured. A component may be replaced; its public contract may not.
Reproducible by constructionDeclarative definition, built from source. Bit-for-bit where achievable, same-inputs-same-result everywhere else, with the input graph recorded.
Verifiable by constructionSBOM and signed attestation per artifact; build, boot and behaviour tests; an append-only log. "It works on my machine" isn't evidence.
Contribute back by defaultUpstreamable patches with their status tracked, and a divergence budget that gets paid down rather than grown.
Boring designs, current versionsWell-understood architectures, latest stable releases, rebase discipline.
Human artistry is protectedBoot experience, theme, which apps ship, keybindings, naming: human-led and AI-assisted, never AI-decided.
The human signs the boundaryThe agent may draft anything. Release signing, update acceptance and privilege changes need independent verification and a person's sign-off.
Continuity lives in artifactsSpecs, tests and build recipes live in the repository as plain text. Agent memory is for task recall, not for the project's memory.
← How PengyOS works Build PengyOS from source →