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:

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
KeyMeaning
imageContainer image to start from (required). Ubuntu, Debian, Fedora, Arch, Alpine… anything distrobox supports.
packagesInstalled with the image's package manager (apt, dnf, pacman, apk) on every apply.
setupShell commands run in the box as you, after the packages, on every apply. Keep them idempotent.
mountsExtra host:guest[:mode] bind mounts, e.g. "/data/models:/models:ro". Your home is always shared.
nvidiaShare 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

← RecipesContainers with podman →