YAML Configuration Syntax - Nitrux/nx-apphub GitHub Wiki

Introduction

The syntax used by NX AppHub CLI is below; we detail each section and key for easier understanding.

1. Syntax description

YAML structure (high-level)

.
├── buildinfo
│   ├── name
│   ├── version
│   ├── binarypath
│   ├── os-target
│   ├── distrorepo
│   │   ├── base
│   │   └── ppas
│   ├── deps
│   └── runtime
├── apprunconf
│   ├── exec
│   ├── setpath
│   ├── setlibpath
│   ├── envvars
│   ├── extra-rpaths
│   └── prebuild-commands
├── sandbox
│   ├── type
│   ├── name
│   ├── aa-profile
│   ├── binds
│   ├── ro-bind
│   └── ...
└── integration
    ├── type
    └── launcher

1.1 Core Package Information

🔹buildinfo

The buildinfo section defines metadata and configuration for building the AppBox, which includes the application name, version, executable path, repositories, dependencies, and other relevant settings.

Note

This syntax page documents what nx-apphub-cli can build in general (including custom bundles). Whether a bundle qualifies as an AppBox in the curated ecosystem follows the canonical policy in FAQ → 1. Why are the files called AppBoxes?.

1.1.1 Supported keys for buildinfo

Key Type Description
name string Name of the application.
version string Version of the package.
binarypath string Path to the application binary inside the Debian package (e.g., /usr/bin/nano).
os-target string Target Nitrux VERSION_ID for curated AppBoxes (for example, 6.1.0). Install is refused when host and target do not match.
distrorepo list or object Either a flat list of repositories or an object with base and optional ppas sections.
deps list List of Debian package dependencies (as strings or as objects with name and repo fields).
runtime string Runtime to use when packaging: classic (FUSE 2/SquashFS), go (FUSE 3/SquashFS), or uruntime (FUSE 3/DwarFS).

Important

For curated entries in nx-apphub-apps, buildinfo.os-target is required and must match the host Nitrux VERSION_ID during install and update.

1.1.2 Repository Information

🔹distrorepo

The distrorepo key defines the list of package repositories used to retrieve dependencies for building an AppBox.

It supports a flat list of repository entries or a structured format with separate base and ppas keys.

Each entry specifies the target Linux distribution, its release codename, architecture, and (optionally) component(s) such as main or universe.

1.1.2.1 Supported keys for distrorepo in YAML list format

Key Type Description
distro string Name of the distribution (debian, debian-snapshot, nitrux, ubuntu, ubuntu-ports, devuan, kde-neon)
snapshot string Required only when distro: debian-snapshot. Debian Snapshot timestamp in the format YYYYMMDDThhmmssZ (for example, 20260725T202958Z).
release string Distribution codename (oracular, sid, stable, duke, etc.)
arch string Target architecture (amd64 or arm64 depending on distro)
components list Optional list of APT components like main, universe, non-free, etc.

Note

When using ubuntu, the only architecture available is amd64. Likewise, when using ubuntu-ports, the available architectures are arm64.

Use snapshot only with debian-snapshot. Do not define snapshot for any other distro entry.

NX AppHub CLI supports specifying a single or multiple repositories in this section.

1.1.2.2 Example #1 - Single repository

  distrorepo:
  - distro: debian
    release: unstable
    arch: amd64
  os-target: 6.1.0
  deps:
    - libexample1
    - libexample2

1.1.2.3 Example #2 - Multiple repositories

  distrorepo:
  - distro: ubuntu
    release: noble
    arch: amd64
  - distro: kde-neon
    release: user
    arch: amd64
    components:
        - main
  deps:
    - libexample1
    - libexample2

1.1.2.4 Example #3 - Debian snapshot repository

  distrorepo:
  - distro: debian-snapshot
    snapshot: 20260725T202958Z
    release: duke
    arch: arm64
  deps:
    - libexample1
    - libexample2

1.1.2.5 Supported keys for distrorepo when using a PPA

Key Type Description
id string A unique identifier for the PPA, referenced in deps.repo.
ppa string The Launchpad PPA identifier in the format user/ppa-name.
distro string Must be ubuntu when using a Launchpad PPA.
release string Ubuntu codename (e.g., oracular, jammy).
arch string Architecture of the PPA binaries (e.g., amd64).

NX AppHub CLI supports using Launchpad PPAs as additional package sources.

To use a PPA, define it in the ppas section of distrorepo, and assign it an id. Then reference that id in the repo field for any dependency on the deps list.

Note

PPAs are only supported when distro: ubuntu is specified.

Important

PPAs are for custom/local builds. Curated YAML definitions in NX AppHub Apps must not use PPAs if they are intended to be considered AppBoxes.

1.1.2.6 Example #4 - Base repository and PPA repository

  distrorepo:
    base:
      - distro: ubuntu
        release: oracular
        arch: amd64
        components: [main, universe]
    ppas:
      - id: ppa-id
        ppa: inkscape.dev/stable
        distro: ubuntu
        release: oracular
        arch: amd64
  deps:
    - name: package-from-ppa
      repo: ppa-id
    - libexample1
    - libexample2

1.1.3 AppRun Configuration

🔹 apprunconf

The apprunconf section defines the runtime environment configuration at application launch.

It controls the execution path, environment variables, binary and library paths, and optional pre-execution commands to set up the environment correctly.

Key Type Description
setpath string Set PATH environment variable inside the AppBox.
setlibpath string Set LD_LIBRARY_PATH for shared libraries.
exec string Path to the executable inside the AppBox.
envvars object Key-value pairs of additional environment variables to set inside the AppBox.
extra-rpaths string | list Add extra RPATH entries to ELF binaries (only for the executable in binarypath).
prebuild-commands list Shell commands to execute during the build process after extracting dependencies but before packaging. Useful for symlinks, cleanup, or pre-configuration.
  • The key envvars supports adding extra paths for LD_LIBRARY_PATH; the paths defined in the YAML will not overwrite the default paths set by NX AppHub CLI in the AppRun.
  • The key extra-rpaths appends the RPATH paths defined in the YAML to the defaults set by NX AppHub CLI; the paths are relative to the path of binarypath ($ORIGIN).
    • For example, if an application requires libblas.so.3 which is in the directory /usr/lib/x86_64-linux-gnu/blas/:
      • $ORIGIN = AppDir/usr/bin (binary location)
      • $ORIGIN/../.. = AppDir
      • $ORIGIN/../../usr/lib/x86_64-linux-gnu/blas = AppDir/usr/lib/x86_64-linux-gnu/blas
    • NX AppHub CLI ensures that RPATH takes priority over LD_LIBRARY_PATH.

1.1.3.1 Example #1 - AppRun configuration

apprunconf:
  setpath: "/usr/bin"
  setlibpath: "/usr/lib"
  exec: "/usr/bin/inkscape"
  envvars:
    ENV_VAR: "VALUE"
  extra-rpaths:
    - "$ORIGIN/../lib/custom"
    - "$ORIGIN/../../plugins"
  prebuild-commands:
    - "touch $APPDIR/hello_world.md"

1.1.4 Sandbox Configuration

The sandbox section in the application specification YAML defines how the system isolates an AppBox at runtime. This section supports multiple sandboxing methods, including bwrap (Bubblewrap), firejail (Firejail), or none (no sandboxing).

Key Type Description
type string Required. Must be none, bwrap, or firejail.

When generating a YAML template, as noted in 1.3 Generating a template YAML, the default value for this section is none.

sandbox:
  type: none

1.1.4.1 Bubblewrap

When using bwrap, you can declaratively enable fine-grained namespace isolation, filesystem restrictions, capability drops, environment control, and bind mounts.

These are expressed as boolean flags or structured lists, allowing precise configuration of the sandbox environment.

Warning

Mounting host directories such as /usr or /lib64 within the sandbox may override the AppBox's bundled libraries, causing conflicts.

Warning

Only mount these paths if: The AppBox requires shared libraries from the host, or you're intentionally relying on the host's dynamic linker or ABI.

Key Type Description
ro-root boolean Mount / as read-only.
dev boolean Mount a new /dev.
proc boolean Mount a new /proc.
tmpfs boolean Mount a tmpfs to /tmp.
mqueue boolean Mount a new /dev/mqueue.
ro-home boolean Mount $HOME as read-only.
no-net boolean Unshare the network namespace (no internet access).
no-ipc boolean Unshare the IPC namespace.
no-pid boolean Unshare the PID namespace.
unshare-user boolean Unshare the user namespace.
unshare-uts boolean Unshare the UTS namespace (hostname/domain).
unshare-cgroup boolean Unshare the cgroup namespace.
new-session boolean Start in a new login session.
cap-drop-all boolean Drop all Linux capabilities.
die-with-parent boolean Terminate the app if its parent dies.
clearenv boolean Clear all environment variables before applying bwrap-env.
hostname string Set hostname inside the sandbox.
chdir string Change to this directory before launching the binary.
file-label string SELinux file label (advanced).
exec-label string SELinux execution label (advanced).
seccomp integer FD for loading a seccomp profile (advanced, uncommon).
bwrap-env list of key-value dicts Environment variables, e.g., - HOME: "$HOME".
bwrap-unset-env list of strings List of environment variables to unset.
cap-drop list of strings Drop specific Linux capabilities (e.g., CAP_SYS_ADMIN).
bind list of strings Bind-mount (e.g., /src:/dst).
ro-bind list of strings Read-only bind-mount (e.g., /src:/dst).
bind-try list of strings Optional bind-mount (ignored if path missing).
ro-bind-try list of strings Optional read-only bind-mount.
remount-ro list of strings Remount existing mounts as read-only (e.g., /etc, /usr).

1.1.4.1.1 Example #1 - Sandbox configuration using Bubblewrap

sandbox:
  type: bwrap
  tmpfs: true
  bind:
    - "$HOME:$HOME"
    - ~/.config:~/.config
  ro-bind:
    - "$APPDIR:$APPDIR"
    - /lib:/lib
  bwrap-env:
    - HOME: "$HOME"
    - LANG: "en_US.UTF-8"
  bwrap-unset-env:
    - DISPLAY

1.1.4.2 Firejail

When set to firejail, the application is launched with Firejail using the default sandboxing profile.

Important

Firejail sandboxing is supported only for integration.type: cli.
integration.type: gui and integration.type: wm must not use sandbox.type: firejail.

Warning

Firejail is a SUID binary; while it provides powerful sandboxing capabilities, it can lead to privilege escalation if exploited. Firejail is not inherently bad, but it's a powerful, sharp tool that cuts both ways; anything that uses SUID root is inherently dangerous.

Note

Nitrux 5.0.0 and newer, apply an AppArmor profile to Firejail itself to limit what Firejail is allowed to do, even when it runs as a SUID root binary, which does mitigate the risk of privilege escalation from a Firejail vulnerability.

To enhance security when using Firejail to sandbox the executable inside the AppDir, you can optionally specify an AppArmor profile using the aa-profile key. This profile must match the executable name within the AppDir, or set to none to disable AppArmor integration with Firejail.

If aa-profile is omitted, it defaults to none.

Note

Firejail's integration with AppArmor is separate from the AppArmor profile applied by Nitrux to Firejail. In other words: AppArmor profile on Firejail itself → Firejail launches the actual executable inside the AppImage/AppBox → Optional AppArmor profile applied to the executable inside the sandbox.

Key Type Description
name string Required for Firejail: Assign a name to the per app Firejail profile.
aa-profile string Optional for Firejail: AppArmor profile to use with Firejail. Set to none for no AppArmor integration with Firejail, or use the name of a valid AppArmor profile matching the internal executable.

1.1.4.2.1 Example #2 - Sandbox configuration using Firejail

sandbox:
  type: firejail
  name: inkscape
  aa-profile: inkscape

1.2 Integration Configuration

The integration section in the YAML specification defines how nx-apphub-cli prepares integration metadata during build, and therefore how the daemon integrates applications into the system.

Warning

When using integration.type with the value wm, sandbox.type must be set to none.

Note

For wm entries, if the session launcher does not include an icon, the integration will default to using preferences-system-windows.

Key Type Description
type string Required. Valid values are gui, cli, or wm.
launcher string Optional. Explicit .desktop launcher file name to use. Leave empty ("") or omit to keep automatic selection.
  • gui: The application appears in application menus.
  • cli: The application is hidden from application menus (NoDisplay=true) and is exposed as a command-line alias by the daemon.
  • wm: The application is a window manager. It is not sandboxed and uses a session launcher; it is also hidden from regular application menus.

When integration.launcher is set:

  • For gui/cli, the file must exist in $APPDIR/usr/share/applications.
  • For wm, the file must exist in either $APPDIR/usr/share/wayland-sessions or $APPDIR/usr/share/xsessions.
  • The value must be a file name (for example, org.kde.plasmashell.desktop), not a path.

If the specified launcher is not found or invalid, the build fails with an error.

Note

For more information about this use-case, see 1. Trade-offs and design limitations under a rootless model: Desktops in an AppBox?

1.2.1 Example #1 - Integrating a command-line app

integration:
  type: cli

1.2.2 Example #2 - Explicit GUI launcher selection

integration:
  type: gui
  launcher: "org.kde.plasmashell.desktop"

1.2.3 Example #3 - Keep automatic launcher selection

integration:
  type: gui
  launcher: ""

1.3 Generating a template YAML

The generate command creates the YAML file in the working directory. This command saves time by automatically filling in the package name, version, dependencies, and repository information.

You can also specify whether the application is a CLI tool or a GUI application, which affects how the daemon integrates them.

Key Type Description
--package string The name of the package (e.g., mc, inkscape).
--distro string The base distribution (e.g., debian, ubuntu, devuan, kde-neon, nitrux).
--release string The release codename (e.g., testing, oracular, sid).
--arch string The CPU architecture: amd64 or arm64 (default: amd64).
--components list Space-separated list of APT components (e.g., main, non-free, universe, etc.) (default: main).
--output string Output filename for the YAML file (default: app.yml).
--integration-type string Integration type: gui, cli, or wm (default: gui).
--description-output string Output filename for generated app description in Markdown (optional).

1.3.1 Example #1 - Basic syntax to generate template YAML

nx-apphub-cli generate \
 --package <package-name> \
 --distro <distro> \
 --release <codename> \
 --arch <arch> \
 --components <component1> <component2> ... \
 --output <file> \
 --description-output <file> \
 --integration-type <gui|cli|wm>
  1. Open the generated file (e.g., app.yml) in a text editor.
  2. Replace the binarypath and exec values with the actual path to the app's executable (e.g., /usr/bin/mc).
  3. Optional fill-in environment variables or pre-build commands.

1.4 Building and validating a YAML file

Use a valid YAML file (e.g., example-app.yaml) and pass it to the NX AppHub CLI as an argument.

  1. Run nx-apphub-cli with the build command and input the path to the YAML file:
nx-apphub-cli build example-app.yaml
  1. Wait for nx-apphub-cli to build the file.
  2. Find the output file in the specified location.

©2026 Nitrux Latinoamericana S.C.

⚠️ **GitHub.com Fallback** ⚠️