onelf

Directories packed into self-contained executables

• Author: @QaidVoid

• Project Page: https://github.com/QaidVoid/onelf

• Docs: https://onelf.qaidvoid.dev

onelf packs a directory into a single self-contained ELF executable. The file carries a trailing footer, a zstd-compressed manifest, and a compressed payload, with a static musl runtime stub at the front that knows how to bring the payload up.

It exists for the case a static binary cannot cover: a program that comes with its own libraries or data files, where upstream ships something dynamically linked and there is nothing to statically link instead.

---

In soarpkgs

type is onelf. These are produced in pkgforge/builds and pinned in soarpkgs like any other release artifact.

---

Prerequisites (HOST)

Nothing in particular. The runtime tries a ladder of execution modes and uses the first one the host supports, so it adapts rather than requiring anything.

Fonts are still the host's, so non-English characters, symbols and emoji need them installed.

Execution modes

memfd                 a static single binary, straight into an anonymous fd
userns + FUSE         private mount, invisible, torn down by the kernel
fusermount3 + FUSE    host-visible mount, still lazy
userns + tmpfs        extracted into a private tmpfs
runtime directory     extracted into a private per-user directory
persistent cache      only on request

Every rung but the last leaves nothing behind when the application exits. Mounting is preferred over extracting wherever the host allows it, since it decompresses blocks on demand and starts fast regardless of package size.

The bottom rung is the one that makes the ladder work. A host with no /dev/fuse, no unprivileged user namespaces and no fusermount3 still has a writable runtime directory, so the package still runs.

The persistent cache is the exception, because it is the one mode that leaves something on disk. The runtime never falls into it on its own: it runs when the package was built with it, when ONELF_CACHE=1 is set, or when it is asked for explicitly.

ONELF_MODE forces a particular rung, which is useful for narrowing down a problem. A forced mode that fails is an error rather than a fallback:

ONELF_MODE=fuse   ./myapp.onelf
ONELF_MODE=rundir ./myapp.onelf

See execution modes for what each one requires and what it costs.

---

Quirks

WARNINGS

• NEVER run strip, objcopy or any other binary rewriting tool. They rewrite the ELF and drop everything past it, which is where the manifest and payload live.

• Desktop entries and icons follow the .onelf/ convention inside the payload, which is how Soar finds them for desktop integration.

• On Ubuntu 23.10 and later, AppArmor restricts unprivileged user namespaces for binaries without an installed profile, which a downloaded file never has. Those hosts land on the fusermount3 rung instead, which works the same way but leaves a mount visible to other processes.