charly-distros

Agent forwarding support -- GPG, SSH, and direnv for .secrets workflow. Use when working with agent forwarding, SSH/GPG socket forwarding, or the agent-forwarding candy.

Base Arch Linux image. Root of the box hierarchy for all pac-based boxes. MUST be invoked before building, deploying, configuring, or troubleshooting the arch box.

Test candy for AUR package installation on Arch Linux. Use when working with the arch-aur-test candy.

Arch Linux builder image with pixi, Node.js, build toolchain, and yay AUR helper. Default builder for pixi, npm, cargo, and aur multi-stage builds on Arch. MUST be invoked before building, deploying, configuring, or troubleshooting the arch-builder box.

Test candy for pacman package installation on Arch Linux. Use when working with the arch-pac-test candy.

Test box for Arch Linux pacman and AUR package installation. MUST be invoked before building or troubleshooting the arch-test box.

CachyOS base image (docker.io/cachyos/cachyos-v3) — x86_64_v3-optimized Arch derivative. Owned by the opencharly/distro-cachyos submodule (box/cachyos); consumed by main's versa box via the `cachyos` import namespace. MUST be invoked before building, deploying, or troubleshooting cachyos boxes.

Bootstrap-from-scratch CachyOS rootfs via pacstrap inside a privileged builder. Builds end-to-end (the shared pacstrap renderer emits Architecture + SigLevel); retained for offline/air-gapped builds. Lives in the opencharly/distro-cachyos submodule (box/cachyos). MUST be invoked before building or troubleshooting cachyos-pacstrap.

Privileged pacstrap builder image for bootstrapping a CachyOS rootfs from scratch. base: arch.arch (via the `arch` import namespace) + the pacstrap-builder candy. Lives in the opencharly/distro-cachyos submodule (box/cachyos). MUST be invoked before building or troubleshooting cachyos-pacstrap / cachyos-vm.

Fedora box with the full charly toolchain using shared candies. Rootless-first — runs as uid=1000 with passwordless sudo (no root, no cap_add: ALL). Same candy list as charly-arch. Includes NVIDIA GPU runtime. MUST be invoked before building, deploying, configuring, or troubleshooting the charly-fedora box.

Cloud-init for instance initialization in cloud/VM environments with NoCloud datasource. Use when working with cloud-init, VM provisioning, or cloud instance bootstrapping.

Rootless nested podman/buildah/skopeo recipe. Ships zero cap_add — works via surgical `unmask=/proc/*` security_opt plus dual-location containers.conf/storage.conf/policy.json plus two canonical env vars plus subuid layout that fits inside the outer user namespace. Authoritative source for the `mount_too_revealing()` kernel RCA. Use when working with nested containers, the container-nesting candy, or any "rootless-in-rootless podman" question.

CUDA toolkit, cuDNN, ONNX Runtime, and NVIDIA GPU development libraries from negativo17 repos. Depends on the nvidia candy for runtime support. Use when working with GPU computing, CUDA, cuDNN, machine learning infrastructure, or NVIDIA development tools.

Base Debian 13 trixie image. Root of the box hierarchy for Debian builds that run as uid 1000 `user` (create mode — Debian 13 ships no pre-existing uid-1000 account). Owned by the opencharly/distro-debian submodule (box/debian); consumed by no main-repo box. MUST be invoked before building, deploying, configuring, or troubleshooting any Debian-based box.

Minimal Debian 13 builder image (pixi + Node.js + build-toolchain) used as the multi-stage builder for every box based on Debian — currently debian-coder. Produces the pre-compiled pixi envs, npm globals, and cargo crates that land in the final runtime image via COPY --from. MUST be invoked before building, deploying, configuring, or troubleshooting the debian-builder box.

Bootstrap-from-scratch Debian rootfs via debootstrap inside a privileged builder (from: builder:debootstrap, bootstrap_builder_image: debian-debootstrap-builder). Retained for offline/air-gapped builds and as a worked example of the from: builder:debootstrap pattern. Lives in the opencharly/distro-debian submodule (box/debian). MUST be invoked before building or troubleshooting debian-debootstrap.

Privileged debootstrap builder image (base: debian:13) — ships the debootstrap toolchain used to bootstrap a Debian rootfs from scratch for debian-debootstrap and the debian-debootstrap VM. Lives in the opencharly/distro-debian submodule (box/debian). MUST be invoked before building or troubleshooting debian-debootstrap-builder.

Base Fedora 43 image. Root of the box hierarchy for all RPM-based boxes. MUST be invoked before building, deploying, configuring, or troubleshooting the fedora box.

Builder image with pixi, Node.js, and C/C++ build toolchain. Used as the default builder for multi-stage image builds. MUST be invoked before building, deploying, configuring, or troubleshooting the fedora-builder box.

Fedora with RPM Fusion non-free repositories enabled. Base for boxes needing codec or proprietary package support like immich. MUST be invoked before building, deploying, configuring, or troubleshooting the fedora-nonfree box.

Test box with Traefik reverse proxy and testapi service. Currently disabled. Used for development testing. MUST be invoked before building or troubleshooting the fedora-test box.

GitHub Actions self-hosted runner as a supervised container service — rootless (uid 1000), Arch/CachyOS packages, credential-backed registration token. Use when working with GitHub Actions runners, CI/CD infrastructure, or runner registration.

Self-hosted GitHub Actions runner on CachyOS, fully rootless — runs as uid=1000 with zero added capabilities (no root, no privileged) via container-nesting, with rootless nested podman/buildah/skopeo for CI. Host networking retained for reachability. MUST be invoked before building, deploying, configuring, or troubleshooting the githubrunner box.

Use when a pod's OWN podman store must be reachable as an API socket — the prerequisite for `charly box load`, and for any in-pod service that spawns containers into the candybox rather than the host store.

NVIDIA GPU base image with runtime support and CUDA toolkit on Fedora. Base for all GPU-accelerated boxes (python-ml, jupyter, ollama, comfyui). MUST be invoked before building, deploying, configuring, or troubleshooting the nvidia box.

NVIDIA GPU runtime support: driver libs, nvidia-container-toolkit (CDI), and VA-API. Fedora (negativo17) and Arch Linux (pac). Base candy for all GPU-accelerated boxes. Use when working with NVIDIA GPU support, CDI device injection, or the nvidia candy.

QEMU guest agent for host-guest communication in virtual machines. Use when working with QEMU/KVM VMs, guest agent setup, or libvirt channel configuration.

AMD ROCm runtime, OpenCL, and GPU compute support via system packages. Use when working with AMD GPU computing, ROCm, HIP, OpenCL, or AMD GPU passthrough in containers.

RPM Fusion free and nonfree repository configuration for Fedora. Use when working with RPM Fusion repos, multimedia codecs, or nonfree packages.

The teaching box quoted end to end by opencharly.ai — a minimal, real dev shell composing one tool candy and one service candy, with the container init injected. MUST be invoked before editing the tutorial-shell box, the check-tutorial-shell bed, or any documentation page that excerpts them.

Base Ubuntu 24.04 noble image. Root of the box hierarchy for Ubuntu- based builds. Runs as uid 1000 `ubuntu` via ADOPT mode — the upstream ubuntu:24.04 base image ships a pre-existing ubuntu:ubuntu account, and the embedded distro.ubuntu vocabulary declares base_user to adopt it verbatim. MUST be invoked before building, deploying, configuring, or troubleshooting any Ubuntu-based box.

Minimal Ubuntu 24.04 builder image (pixi + Node.js + build-toolchain) used as the multi-stage builder for Ubuntu-based boxes — currently ubuntu-coder. Runs as uid 1000 `ubuntu` (adopted from the upstream ubuntu:24.04 base image via the embedded distro vocabulary's base_user declaration). MUST be invoked before building, deploying, configuring, or troubleshooting the ubuntu-builder box.

Bootstrap-from-scratch Ubuntu 24.04 rootfs via debootstrap inside a privileged builder (from: builder:debootstrap, bootstrap_builder_image: ubuntu-debootstrap-builder). Retained for offline/air-gapped builds. Lives in the opencharly/distro-ubuntu submodule (box/ubuntu). MUST be invoked before building or troubleshooting ubuntu-debootstrap.

Privileged debootstrap builder image (base: debian:13 — debootstrap is a Debian tool that bootstraps Ubuntu suites too) — ships the debootstrap toolchain for ubuntu-debootstrap and the ubuntu-debootstrap VM. Lives in the opencharly/distro-ubuntu submodule (box/ubuntu). MUST be invoked before building or troubleshooting ubuntu-debootstrap-builder.

Test box with Valkey (Redis-compatible) key-value store. Currently disabled. Used for development testing. MUST be invoked before building or troubleshooting the valkey-test box.

Mounts a virtiofs share tagged `workspace` at /workspace inside a VM guest via a systemd .mount unit. Use when a kind:vm entity shares a host directory into the guest and you need it auto-mounted (and re-mounted at every boot).