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
| Layer | Decision | Why |
|---|---|---|
| Build engine | Buildroot 2026.08, pinned, with our own BR2_EXTERNAL tree of boards, defconfigs and recipes | the keystone decision: it decides what "reproducible" can mean |
| Kernel | Linux 7.2, pinned, configured per hardware, not patched | latest stable by policy; a configured kernel beats a forked one |
| Boot | GRUB (UEFI), one kernel per slot, switched through grubenv; Plymouth splash on the Desktop | boring and proven. Slot switching without UKIs |
| Init | systemd, kept for the contract (unit semantics, targets) | compatibility over novelty. Its interior can be replaced, its contract may not |
| Storage | Read-only ext4 system in A/B slots, plus a btrfs data partition for everything that is this machine; /etc is an overlay | an update swaps the system, never your files |
| Our code | Rust for system components (the installer GUI, desktop pieces), Python for tooling, C upstream | the right tool for each job |
| Provenance | SPDX SBOM in every image, ed25519-signed release manifests. Secure Boot and measured boot are not enforced yet | trust 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
| Step | What happens |
|---|---|
| Observe | Track 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. |
| Propose | The agent drafts the change (a version bump, a patch, a new component) with its justification and files it. It does not apply it. |
| Build | A reproducible build produces the artifact and its SBOM. |
| Verify | An independent witness boots the image and runs the behaviour tests. The agent's own tests are necessary but not sufficient. |
| Ratify | A 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
| Tier | Surface | Who may change it | How |
|---|---|---|---|
| 0 — Base | Kernel, libraries, the image itself | nobody at runtime | a 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' data | the admin, or the agent | lives on the data partition and is never touched by an update. Snapshots and a change journal are planned, not built yet |
| 2 — Critical | Signing keys, the update trust root, privilege changes | a human signs | a 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
| Principle | What it means in practice |
|---|---|
| Freedom first | MIT 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 derive | Compatible with the Linux world, derived from no distro. No inherited configuration, patch sets or packaging decisions. |
| Compatibility is a contract | POSIX, ELF, systemd unit semantics, D-Bus, Wayland and freedesktop are honoured. A component may be replaced; its public contract may not. |
| Reproducible by construction | Declarative definition, built from source. Bit-for-bit where achievable, same-inputs-same-result everywhere else, with the input graph recorded. |
| Verifiable by construction | SBOM 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 default | Upstreamable patches with their status tracked, and a divergence budget that gets paid down rather than grown. |
| Boring designs, current versions | Well-understood architectures, latest stable releases, rebase discipline. |
| Human artistry is protected | Boot experience, theme, which apps ship, keybindings, naming: human-led and AI-assisted, never AI-decided. |
| The human signs the boundary | The agent may draft anything. Release signing, update acceptance and privilege changes need independent verification and a person's sign-off. |
| Continuity lives in artifacts | Specs, tests and build recipes live in the repository as plain text. Agent memory is for task recall, not for the project's memory. |