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.
| Edition | What you get | Installs & updates |
|---|---|---|
| Core | systemd, 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. |
| Server | Core 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 NVIDIA | The 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. |
| Desktop | Server 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 NVIDIA | The 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:
- The system is read-only.
/usr,/usr/local,/optand the rest of the root come from the image, byte for byte. You can't (and don't need to) change them. A new version arrives as a whole new image in the other slot. /home,/varand/rootlive on the data partition. Your files, containers, Flatpak apps, logs and databases all live here./etcis an overlay. The image supplies the defaults and your changes are stored on the data partition on top of them. Edit/etcas usual (withsudo) and the change sticks, through updates too. If an update changes a default in a file you've edited, your version wins.- Swap is compressed RAM (zram), so there is no swap partition to size.
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:
| Way | Good for | How |
|---|---|---|
| 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 directory | Single-binary tools and language toolchains: uv, Go, rclone, Syncthing | Put binaries in ~/.local/bin, which is already on your PATH. See the recipes. |
| Containers | Services: web servers, databases, anything with a Docker image | Rootless podman; recipe. |
| The dev box | Compilers, apt install, anything that expects a "normal" distro | pengyos-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
- The installer creates your user and puts it in the
wheelgroup, which may usesudo(with your password). When a Desktop app needs admin rights, it asks for your password, not root's. Installing and updating Flatpak apps and installing system updates don't ask at all. - On the Desktop your shell is
zsh, with~/.local/binon thePATH. Add more people under Settings → Users. - The Desktop asks for your password at boot. To log straight in instead, run
sudo pengyos-autologin on.offturns the login screen back on.
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:
- 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.
- It writes the new system into the other slot. The slot you're running is left alone.
- 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
- Backups: every night at 02:00,
pengyos-backupwrites a compressed tarball of/etcand/hometo/var/backups/pengyosand keeps the newest 7. Settings are in/etc/pengyos/backup.conf. This protects against mistakes, not a dead disk, so copy it off the machine as well. rclone or Syncthing can do that.Before 26.10.0 the nightly tarball failed every run (the image's
tarcouldn't compress), so a machine on an older release has no backups in/var/backups/pengyos. Update withsudo pengyos-update apply. - Monitoring: every hour, load average, memory and disk use for
/,/varand/homeare added to/var/log/pengyos-monitor.log(/etc/pengyos/monitor.conf). - Logs: everything else is in the journal.
journalctl -bshows this boot,journalctl -u sshdshows one service, andsystemctl --failedlists what broke.
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.