RunImage

RunImage is a portable single-file Linux container format, created by @VHSgunzo. Packages are built on top of a base RunImage.

pkg_type: runimage

Features

• Built-in sandboxing (usage docs)
• Self-contained runtime with full rootfs
• No host dependencies
• Can run without FUSE

Prerequisites

• FUSE — required for mounting (can be bypassed, see below)
• Fonts — for rendering non-Latin characters and emojis
• User Namespaces — required for sandboxing

Running Without FUSE

# Per-invocation
./app.runimage --runtime-extract-and-run

# Via environment variable
export RUNTIME_EXTRACT_AND_RUN=1
./app.runimage

Quirks

DANGER

• Never run strip, objcopy, or any binary rewriting tool on RunImages. They will destroy the embedded squashfs|dwarfs archive, leaving only the runtime stub.
• A .runimage file is not a real ELF binary.

Example SBUILD

#!/SBUILD
_disabled: false

pkg: "mytool"
pkg_id: "github.com.user.mytool"
pkg_type: "runimage"
ghcr_pkg: "user/mytool"
description: "My CLI tool"
provides:
  - "mytool"
src_url:
  - "https://github.com/user/mytool"
x_exec:
  host:
    - "aarch64-linux"
    - "x86_64-linux"
  shell: "bash"
  pkgver: |
    curl -qfsSL "https://api.github.com/repos/user/mytool/releases/latest" | jq -r '.tag_name'
  run: |
    soar dl "https://github.com/user/mytool" --match "runimage" -o "./${PKG}" --yes

See Also

• RunImage GitHub
• RunImage Base