uruntime

This is the Anylinux-uruntime fork of uruntime. It tracks upstream version 0.8.1 and adds support for a leading metadata SquashFS image, so SquashFS-only thumbnailers and desktop integration tools can read metadata from DwarFS AppImages.

uruntime is a static runtime for RunImage and AppImage. It launches appended SquashFS and DwarFS images through FUSE, with extraction as a configurable fallback when FUSE is unavailable.

A single ELF contains the launcher and static filesystem tools. Runtime settings, environment variables, signatures, and update information can be changed after an image has been built, without recompiling the runtime or repacking its filesystem.

Highlights

• AppImage and RunImage support.
• SquashFS and DwarFS support in one runtime or filesystem-specific builds.
• Fully static binaries for six Linux architectures.
• FUSE mounting, forced extraction, and automatic extraction fallback.
• Safe reuse of shared mounts and extracted directories across overlapping launches.
• User and mount namespaces with optional UID/GID mapping and capability dropping.
• Portable home, data, config, and cache directories beside the image.
• Embedded filesystem tools that can be called through runtime options or executable names.
• Mutable ELF sections for environment variables, signatures, and update information.
• Operation without procfs when the selected launch mode does not require it.

How it works

When an image starts, uruntime:

1. finds and validates the appended SquashFS or DwarFS image;
2. mounts it through FUSE or extracts it according to the configured policy;
3. prepares namespaces, portable directories, and the runtime environment;
4. starts AppRun for AppImage or Run.sh for RunImage;
5. keeps shared targets alive while participating application trees are still running, then cleans them up according to the reuse policy.

Filesystem helpers are stored inside the runtime in Zstd-compressed form and normally run through memfd. Cleanup fails safe: if uruntime cannot prove that a shared target is no longer in use, it retains the target instead of deleting active data or unmounting a live filesystem.

The complete launch, fallback, reuse, supervision, and cleanup model is documented in Application launch, lifetime, and cleanup.

Runtime variants

Each release contains nine variants per architecture:

Variant	Format	Filesystems	Contents
runimage	RunImage	SquashFS + DwarFS	full
runimage-squashfs	RunImage	SquashFS	full
runimage-dwarfs	RunImage	DwarFS	full
appimage	AppImage	SquashFS + DwarFS	full
appimage-lite	AppImage	SquashFS + DwarFS	mount/extract only
appimage-squashfs	AppImage	SquashFS	full
appimage-squashfs-lite	AppImage	SquashFS	mount/extract only
appimage-dwarfs	AppImage	DwarFS	full
appimage-dwarfs-lite	AppImage	DwarFS	mount/extract only

Full variants can create and check filesystem images. Lite variants retain the tools needed to mount and extract them.

Supported release architectures are x86_64, aarch64, riscv64, loongarch64, ppc64, and ppc64le. See the build guide for Rust targets and cross-build details.

Getting a prebuilt runtime

Download a runtime from Releases, choose the required variant and architecture, then make it executable:

chmod +x uruntime-appimage-x86_64
./uruntime-appimage-x86_64 --appimage-help

Common operations:

# Show the image offset
./My.AppImage --appimage-offset

# Extract the image
./My.AppImage --appimage-extract

# Run without FUSE
./My.AppImage --appimage-extract-and-run

# Create portable directories beside the image
./My.AppImage --appimage-portable-home
./My.AppImage --appimage-portable-config

AppImage options use the --appimage-* prefix and RunImage options use --runtime-*. The universal --uruntime-* prefix works with both formats. See the usage reference for all commands and embedded tools, and the configuration reference for launch policies and environment variables.

Building

The project uses the pinned Rust nightly from rust-toolchain.toml. Repository build, test, and release orchestration is implemented in Rust through xtask.

git clone https://github.com/pkgforge-dev/Anylinux-uruntime.git
cd Anylinux-uruntime
rustup component add rust-src rustfmt clippy

# Run the canonical local gate
cargo --locked xtask check

# Build nine variants for x86_64
cargo --locked xtask x86_64

See Building uruntime for prerequisites, targets, toolchains, helper verification, and artifact validation.

Projects using uruntime

• AnyLinux-AppImages — a collection of AppImage build scripts for many Linux applications.
• appimagetool — a Rust AppImage builder that packages AppDirs as DwarFS images with uruntime, including pinned runtime resolution and ELF section configuration.
• CPU-X — a system information and hardware monitoring application.
• Converseen — a batch image conversion and resizing application.
• Eden — a Nintendo Switch emulator.
• Ghostty AppImage — a portable AppImage build of the Ghostty terminal.
• GOverlay — a graphical configurator for MangoHud, vkBasalt, and related gaming tools.
• Interstellar — a client for Mbin, Lemmy, and PieFed.
• MangoJuice — a graphical configuration tool for MangoHud.
• PPSSPP — a PlayStation Portable emulator.
• QDiskInfo — a graphical frontend for smartctl and drive SMART data.
• RPCS3 — a PlayStation 3 emulator.
• RSS Guard — a desktop client for RSS, Atom, and other feed formats.

Documentation

• Usage reference
• Configuration reference
• Application launch, lifetime, and cleanup
• Building uruntime
• Testing uruntime
• Release procedure
• Release history

License

MIT