Recipe Schema

Full schema for onelf.toml. See Recipe File for the user-facing guide.

Top level

[package]
# required fields, plus optional metadata

[[entrypoint]]
# zero or more extra entrypoints

[compression]
# optional, sensible defaults

[update]
# optional, enables self-update

[bundle]
# optional, passes to bundle-libs

Unknown fields are rejected (deny_unknown_fields) to catch typos.

[package]

[package]
name = "myapp"                    # Option<String>, defaults to basename of command
command = "bin/myapp"             # String, required
output = "myapp.onelf"            # Option<PathBuf>, relative to recipe dir
working-dir = "inherit"           # "inherit" | "package" | "command"
memfd = true                      # Option<bool>, overrides auto-detect
exclude = ["*.a", "__pycache__"]  # Vec<String>, path globs
version = "1.2.3"                 # Option<String>
description = "..."               # Option<String>
license = "MIT"                   # Option<String>
homepage = "https://..."          # Option<String>

working-dir values:

• inherit: preserve the caller's cwd
• package: cwd is the AppDir root at runtime
• command: cwd is the directory containing the entrypoint binary

[[entrypoint]]

[[entrypoint]]
name = "myapp-daemon"   # String, required; selected via argv[0]
path = "bin/myapp"      # String, required; relative to AppDir
args = ["--daemon"]     # Vec<String>, prepended to invocation
default = false         # bool, mark as default entrypoint

The [package].command entrypoint is always added first and implicitly default unless another entry has default = true.

[compression]

[compression]
level = 12     # i32, 0..=22, default 12
dict = false   # bool, default false

Higher levels pack tighter but are slower. dict = true trains a shared zstd dictionary across blocks, which helps ratios for packages with many small text files.

[update]

[update]
url = "https://releases.example.com/myapp.onelf.zsync"

When present, onelf selects the update-capable runtime (~1.3 MB larger than slim).

[bundle]

[bundle]
lib-dirs = ["auto"]              # default ["auto"]; listed dirs become LD_LIBRARY_PATH
search-paths = [
  "${MUSL_LIBDRM}/lib",
  "/opt/custom/lib",
]                                # Vec<String>, supports ${VAR}
exclude = ["libpthread"]         # Vec<String>, soname prefixes to skip
include = ["libfoo.so.1"]        # Vec<String>, force-include sonames
gl = false                       # auto-enabled from DT_NEEDED
dri = false                      # auto-enabled
vulkan = false                   # auto-enabled
wayland = false                  # auto-enabled
gtk = false                      # auto-enabled
strip = false                    # run strip --strip-unneeded
strict-libc = false              # skip wrong-family libc libs
scan-dlopen = false              # scan strings for common dlopen'd libs
dlopen = ["libmyvendor.so.1"]    # extra sonames for scan-dlopen allow-list
skip = false                     # don't run bundle-libs at all (pre-bundled AppDir)

Env var expansion

All string fields support ${VAR} expansion from the process's environment at recipe load time. Missing variables expand to empty strings.