PengyOS / Docs / How it works

How PengyOS works

PengyOS behaves like an appliance at the bottom and like any Linux machine at the top. The system is one signed image that is replaced as a whole. Everything that makes the machine yours lives on a separate partition and is never touched by an update.

The editions

There is one base and three layers, and each one only adds to the one below it. A Desktop has everything a Server has, and a Server has everything Core has.

EditionWhat you getInstalls & updates
Coresystemd, networking (DHCP), key-only SSH, Python 3, disk tools, firmware for common hardware. About 224 MB of RAM when idle.Runs from the disk you write it to. No installer, no updates yet.
ServerCore plus rootless podman, distrobox and the dev box, git, curl, zsh, tmux, mosh, ripgrep, fd, jq, bat, eza, zoxide, Python with pip, a default-deny firewall, daily backups and hourly monitoring.Console installer; signed A/B updates.
Server NVIDIAThe Server plus NVIDIA's driver for GPU computing (the open kernel modules with NVIDIA's userspace: CUDA, nvidia-smi, video encode/decode; no graphics) for GeForce RTX 20 cards and newer, GPUs in podman containers, and a cuda dev box.Same as Server.
DesktopServer plus the COSMIC desktop behind a login screen, Wi-Fi, Bluetooth, PipeWire audio, printing and scanning, Xwayland, Vulkan, Flatpak with Flathub, and the PengyOS Updates app.Graphical installer from a live desktop; signed A/B updates.
Desktop NVIDIAThe Desktop plus NVIDIA's driver (the open kernel modules with NVIDIA's userspace, CUDA included) for GeForce GTX 16 / RTX cards and newer, and a cuda dev box.Same as Desktop.

Every image runs on any 64-bit UEFI PC. Secure Boot must be off for now.

The disk: system slots and data

The installer lays the disk out like this:

┌─────────┬──────────────┬──────────────┬──────────────────────────────────────────┐ │ ESP │ root-a │ root-b │ data (btrfs, the rest of the disk) │ │ 256 MiB │ 8 GiB, ext4 │ 8 GiB, ext4 │ subvolumes: etc var home root │ │ GRUB + │ the system │ the other │ │ │ kernels │ (read-only) │ system slot │ everything that is *this machine* │ └─────────┴──────────────┴──────────────┴──────────────────────────────────────────┘

Rule of thumb: if a guide tells you to install something into /usr or /opt, install it into your home directory or a container instead. Every recipe in these docs does it that way.

Where software comes from

There's no package manager on the system itself: the image is the package. You add software in four ways, from most to least integrated:

WayGood forHow
Flatpak (Desktop)Desktop apps: Firefox, Chrome, Steam, Discord, VS Code, GIMP, Spotify…The COSMIC Store, or flatpak install flathub <app-id>. Flathub is set up on first boot.
Your home directorySingle-binary tools and language toolchains: uv, Go, rclone, SyncthingPut binaries in ~/.local/bin, which is already on your PATH. See the recipes.
ContainersServices: web servers, databases, anything with a Docker imageRootless podman; recipe.
The dev boxCompilers, apt install, anything that expects a "normal" distropengyos-guest enter dev, an Ubuntu container that shares your home; recipe.

There is no C compiler on the system. That's a deliberate choice of how the image is built. Anything that needs gcc, make or cargo to link runs in the dev box. Pure Python, prebuilt wheels and Go (without cgo) work right on the host.

If something should be part of the system for everyone, such as a driver, a daemon or a library, it belongs in the image. That's a change to the build definition (see Build PengyOS), and it ships to every machine in the next update.

Your account and admin rights

SSH

Every Server and Desktop runs sshd. It accepts keys only, never passwords. Each machine generates its own host keys on first boot. The Server installer can add your public key for you. Because passwords are refused, ssh-copy-id can't add the first key. Add it from a terminal on the machine itself (or over an SSH session that already works):

# on the PengyOS machine, as the user you'll log in as; paste your *public* key
mkdir -p ~/.ssh && chmod 700 ~/.ssh
echo 'ssh-ed25519 AAAA…your-key… you@laptop' >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Root can log in with a key (PermitRootLogin prohibit-password) once one is in /root/.ssh/authorized_keys.

The firewall

Server and Desktop start with a default-deny nftables firewall. Inbound traffic is allowed only for SSH (port 22), mDNS (printer and host discovery), ping, and replies to connections you made. Everything outbound is allowed. The ruleset is one readable file, /etc/nftables.conf.

Opening a port

Add a line next to the SSH rule in the input chain:

        tcp dport 22 ct state new accept
        tcp dport 8080 ct state new accept            # ← e.g. a web server
        udp dport 22000 accept                        # ← UDP has no "new" state to match

Check the file, then load it:

sudo nft -c -f /etc/nftables.conf     # syntax check, changes nothing
sudo systemctl restart nftables       # apply
sudo nft list ruleset                 # see what is live

To limit a port to your LAN, match the source: ip saddr 192.168.1.0/24 tcp dport 8080 ct state new accept. The change lives in the /etc overlay, so it survives updates.

Updates and rollback

Releases are published to the update feed. Each one is a complete system image, signed with the PengyOS release key. Every installed machine checks once a day. On the Desktop, PengyOS Updates shows what's new, installs on request and reminds you only as often as you want. Otherwise, use the terminal:

pengyos-update status                # this version, the channel, both slots
pengyos-update check                 # is there something newer?
sudo pengyos-update apply --reboot   # install it and restart into it
sudo pengyos-update rollback         # make the previous version the default again
sudo pengyos-update channel testing  # new releases first (or: stable)

What apply does:

  1. It downloads the release for this machine's edition and checks its signature against the keys shipped in the running image. It refuses anything unsigned, a different edition, or an older version.
  2. It writes the new system into the other slot. The slot you're running is left alone.
  3. The next boot tries the new slot once. If it starts cleanly, it becomes the default. If it doesn't, the following boot goes back to the old slot by itself.

Your data partition is never touched, so accounts, Wi-Fi, apps, containers and files all carry over.

Backups, monitoring, logs

Pengy, the built-in agent

Every edition ships Pengy, an AI assistant that can explain and administer the machine. It's pengy-cli in a terminal, pengy-web in a browser (Server and Desktop), and the Pengy app on the Desktop. It ships unconfigured: nothing talks to a model until you point it at one. Set up Pengy.

← DocsRecipes →