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/.