PengyOS / Docs / Recipes / The dev box
The dev box
PengyOS has no compiler and no apt on the system. The dev box gives you both: an
ordinary Ubuntu 24.04 container that shares your home directory, your user, the network and the
display with the host. Edit on the host, build in the box, and the results land in your home.
ServerDesktop
Enter it
pengyos-guest enter dev
The first time, this pulls Ubuntu and provisions it. That takes about a minute and a half on a fast connection. After that, entering is near-instant. You get a shell in the box with your prompt, your home and your files, and with:
build-essential(gcc, g++, make),cmake,ninja-build,pkg-config,git,curl,wgetpython3+python3-venv, and uv- Ubuntu's
golangpackage (see Go for a current one) - rustup with the stable Rust toolchain in
~/.cargo
Run one command without opening a shell; its exit code comes back to you:
cd ~/src/myproject
pengyos-guest enter dev -- make -j"$(nproc)"
Install more
sudo apt install works inside the box as usual. It changes the box, never the host:
pengyos-guest enter dev
sudo apt install libsqlite3-dev valgrind
A box can be thrown away and rebuilt at any time, so anything you'd miss after a rebuild belongs in its definition (below), not only in the box.
Use a box app from the host
Export a program as a launcher in ~/.local/bin. GUI apps also get an entry in the app menu:
pengyos-guest export dev --app code # e.g. after installing VS Code's .deb in the box
Make it yours
The image ships the definition in /usr/share/pengyos/guests.d/dev.toml. To change
it, write your own version to ~/.config/pengyos/guests.toml. A guest you define
replaces the shipped one with the same name. Then rebuild:
# ~/.config/pengyos/guests.toml
[guests.dev]
description = "My build box"
image = "docker.io/library/ubuntu:24.04"
packages = ["build-essential", "cmake", "git", "curl", "libsqlite3-dev", "valgrind"]
setup = [
"echo 'export PATH=\"$HOME/.cargo/bin:$HOME/.local/bin:$PATH\"' | sudo tee /etc/profile.d/pengyos-dev.sh >/dev/null",
"command -v rustup >/dev/null || curl -fsSL https://sh.rustup.rs | sh -s -- -y --no-modify-path",
]
[guests.fedora]
description = "A Fedora box"
image = "registry.fedoraproject.org/fedora:42"
packages = ["gcc", "make", "git"]
pengyos-guest destroy dev # removes the container; your home is untouched
pengyos-guest enter dev # recreated from your definition
pengyos-guest list # every guest this machine knows, and whether it exists
| Key | Meaning |
|---|---|
image | Container image to start from (required). Ubuntu, Debian, Fedora, Arch, Alpine… anything distrobox supports. |
packages | Installed with the image's package manager (apt, dnf, pacman, apk) on every apply. |
setup | Shell commands run in the box as you, after the packages, on every apply. Keep them idempotent. |
mounts | Extra host:guest[:mode] bind mounts, e.g. "/data/models:/models:ro". Your home is always shared. |
nvidia | Share the host's NVIDIA driver with the box (NVIDIA images). |
pengyos-guest apply [name…] creates and provisions guests without entering them.
CUDA (NVIDIA images)
The NVIDIA images (Server NVIDIA and Desktop NVIDIA) also ship a cuda guest, built from NVIDIA's
cuda:13.1.0-devel-ubuntu24.04 with the host driver passed through. It's the place to
build CUDA code such as llama.cpp:
pengyos-guest enter cuda -- nvidia-smi
Good to know
- Binaries usually run on the host too. Ubuntu 24.04's C library is older than PengyOS's, so programs built in the box run on the host as long as the shared libraries they link are on the host as well. glibc, OpenSSL, zlib and the like are. If one isn't, run it in the box or link it statically.
- It's distrobox underneath.
pengyos-guestadds the declarative definitions. Plaindistrobox createanddistrobox enterwork too. - The box isn't a sandbox. It shares your home and runs as you. Don't run anything in it you wouldn't run on the host.