PengyOS / Docs
PengyOS documentation
How the system is put together, how to get everyday things done on it, and how to build the whole operating system yourself.
New here? Start with the download and install guide
to get PengyOS onto a machine, then read How PengyOS works. It's
a ten-minute read, and it explains why there is no apt install and what to do
instead.
Guides
Install in a virtual machine
Try the Server or Desktop in QEMU/KVM, virt-manager or a VM farm: UEFI, the installer ISO as a CD, a blank disk.
How PengyOS works
The editions, the read-only system and what survives an update, where software comes from, admin rights, SSH, the firewall, updates, backups.
How PengyOS is put together
The base image and why each layer was chosen, where software comes from, the maintenance loop, what may change without a signature, and the ten principles.
Set up Pengy
Point the built-in agent at a model: a server on your network, llama.cpp on the machine, or a hosted API.
How PengyOS was built
One person and AI agents: small tested tools written overnight, a gate their own tests couldn't fool, and the parts done by hand on real hardware.
Build PengyOS from source
Set up a build host, build COSMIC and every edition, test the images in a VM, write them to a stick, and publish your own signed updates.
Download & install
Pick an edition, write it to a USB stick, start from it and install. Checksums are signed with the release key.
Release feed
Every release and its notes, as a page and as an Atom feed. Installed machines read the same feed.
Recipes
Short, tested how-tos for common jobs on the Server and Desktop editions. All recipes →
The dev box
A full Ubuntu toolchain in a container that shares your home directory.
Containers with podman
Run nginx and MongoDB, keep them running across reboots, open a port.
Python with uv
Projects, virtual environments, other Python versions, command-line tools.
Rust with rustup
Build in the dev box; run the binaries on the host.
Go
The upstream toolchain in your home directory. It builds right on the host.
llama.cpp
Run a language model on your own machine, on the CPU or a GPU, for Pengy.
Syncthing
Continuous file sync between your machines, as a user service.
rclone
Copy, sync and mount cloud storage: S3, Google Drive, B2 and others.
Design documents
The project keeps its design record in plain text next to the source, and the repository is public:
github.com/patw/pengyos. Start with
README (why PengyOS exists) and
SPEC (the component stack and the
alternatives each decision beat), then
USE-CASES (the user stories that
become tests) and the
CHANGELOG. The install/update and
testing documents are in docs/.