PengyOS / Docs / How it was built
How PengyOS was built
PengyOS went from an empty repository to four editions running on real machines in about three weeks, built by one person working with AI agents. This page is the honest account of how: what the agents did well, what they got wrong, and what had to change along the way.
The split: tools, not the distro
An agent can't "build a Linux distribution" in one go. A Buildroot run takes hours, booting an image needs a VM, and the interesting failures happen on real hardware. So the work was split along one line:
- The distro itself, meaning which packages, kernel options and boot chain, and getting images to boot, was driven by a person working with a frontier model in an interactive session.
- The tools the distro is built and checked with were written by a local model running unattended overnight: the build driver, the QEMU boot tester, the SBOM generator, the signing tool, the updater, the installer engine and dozens more. Each was a small project with its own tests.
That's why the repository has a tools/ directory with dozens of small,
independently tested projects rather than one large program.
The overnight loop
The loop (called Ralph, after the technique of running an agent in a loop until its task is done) worked through a queue of tasks between evening and morning on the build server. A task was shaped so a local model could finish it without help:
- A written spec first. The frontier model wrote each tool's
spec.md(the interface, the acceptance criteria, what was out of scope) and a checklist of small subtasks, one per iteration. - An objective function. Each tool had a pinned
verify.toml, its test command. An iteration counted only if the suite stayed green. - No privileges. No root, no network at test time, no real hardware. Anything that needed those was mocked or put behind an opt-in integration flag, and a task that needed root stopped and asked.
- Review before merge. Each finished tool landed on its own branch for a person to read and merge.
Tools were queued in waves by dependency: first the build driver and the boot tester, then supply-chain tools (pinned versions, licenses, upstream watching, advisory triage), then the update and install machinery, then the Desktop pieces.
Green tests, broken wiring
The loop's weakness showed up quickly. A tool's test suite is written by the same agent that writes the tool, so it agrees with the tool even when both are wrong. On a single day, three tools passed every test while being broken in the actual tree:
- the NVIDIA tool wired its files into the wrong directory and built its configuration on the wrong base, and its 154 tests checked the wrong layout;
- the audio tool shipped an
/etc/groupthat replaced the system's instead of adding to it, deleting therootgroup, and the image build died; - a recipe tool wrote Buildroot recipes that had never been built and couldn't be.
The fix was a check the loop couldn't edit: scripts/pengyos_gate.py lives in the
repository, outside any task, and checks the things a tool's own tests can't see: that wiring
tools' output is really in the tree, that overlays don't clobber system files, that every recipe
downloads and verifies. It still runs on every change.
What was done by hand
The parts that make PengyOS a working system rather than a pile of tools were done interactively, mostly on real hardware:
- bringing up each edition in Buildroot, the defconfig layers, and the kernel options for every machine in the test fleet;
- getting COSMIC to run on a from-source system (missing libraries, portals, the greeter);
- the install and update design that shipped: two read-only system slots chosen by GRUB, a data partition updates never touch, signed manifests;
- the updater and the PengyOS Updates app, written directly without the loop;
- everything that only shows up on hardware: touchpads, Wi-Fi firmware, audio codecs, the boot splash handing over to the graphics driver.
A full UKI and systemd-boot design was specified and built as tools first. When the simpler GRUB layout shipped and covered every user story, those tools were retired.
After the loop
Once the toolkit existed, the loop was switched off and its working files (per-task checklists,
prompts, run notes) were deleted. They described how the code was written, not what it does.
What remains from that phase is each tool's spec.md, its tests, and its
verify.toml, which the gate now runs for every tool on every push.
Since then, development has been a person and an agent working in one session. The agent drafts, builds and boot-tests, and the person decides and signs. Signing a release, accepting a key and changing a privilege boundary always need a human.
The maintenance loop came later and runs on its own. It reads upstream releases and the CVE feeds every night, triages them, batches the changes into one build, boot-checks the result and publishes it to the testing channel. Nobody prompts it. See the maintenance loop for what it is and isn't allowed to decide.
What we'd keep
- Small tools with specs written first. A local model is good at a bounded task with a clear contract and a test command; it is bad at deciding what the task is.
- A check the author can't change. Agent-written tests prove the code matches the agent's understanding, not that it works. An external gate, a boot test and real hardware do.
- Boot it, look at it. A green build log and an active unit can still mean a black screen. Every image change is booted, and the Desktop is checked with a screenshot.
- Delete scaffolding when it's done. Notes that made sense to the loop became misleading once the code moved on.
Build your own
None of this is specific to PengyOS, and none of it is secret. The time for vibe-coded Linux distributions is here: a person with an agent that can work for hours, a spec it has to satisfy, and one check it isn't allowed to edit can get an operating system out the door.
So if PengyOS isn't the distro you want, don't argue with it — copy it. SPEC.md is the whole design in one file: every component, why it was chosen, and what it beat. The parts worth stealing are the shape of the thing: decisions written down before the code, small tools with a written spec and their own tests, and a gate outside any task that the agents can't edit. It's a big project. AI is what makes it a project you can actually finish.