RunImage

Portable single-file Linux container, similar to FlatImage

• Author: @VHSgunzo

• Project Page: https://github.com/VHSgunzo/runimage

• Base: an Arch Linux rootfs, with packages installed into it and the result repackaged

A RunImage is a single-file Linux container. It runs in unprivileged user namespaces, mounts a DwarFS or SquashFS payload through the uruntime, and does its containment with a statically compiled bubblewrap. The binaries inside are static and wired up with sharun, so nothing is taken from the host.

pkgforge-dev/runimage-base, which built the base images we used, is archived. Upstream's own rootfs is the live one.

---

In soarpkgs

Soar installs this format from a repository, a URL, or a local file, and a recipe can name it as its type. No package in soarpkgs happens to use it at the moment.

---

Prerequisites (HOST)

• Kernel user namespaces: the real requirement, since the container is unprivileged. Kernel 5.0 or newer is recommended.

• Fuse: preferred but not required. Without it the image runs unpacked, through --runtime-extract-and-run or RUNTIME_EXTRACT_AND_RUN=1.

• Fonts: required to display/render non-English characters, symbols and emoji.

---

Sandbox

RunImages sandbox through bubblewrap, tuned with RIM_UNSHARE_* environment variables for the home directory, host processes and so on. See usage for the full set.

---

Quirks

WARNINGS

• NEVER run strip, objcopy or any other binary rewriting tool as they will often just strip the squashfs|dwarfs archive, only preserving the runtime.

• A typical .runimage file is not a real elf binary, thus will not survive this process.

• A RunImage carries a distribution rather than an application, so it is considerably larger than the equivalent AppImage or static binary.