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:

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:

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 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:

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

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.

← How it worksBuild it →