apx: a package manager wrapper that runs commands inside managed containers

Four commands, and subsystems underneath

apx, pronounced with the initialism given in the readme, is the default package manager in Vanilla OS. The description is the whole idea in one sentence: it is a wrapper around multiple package managers to install packages and run commands inside a managed container.

The help output is short, which is unusual for a package manager and is worth reading as a design signal:

Usage: apx [flags] [command]

Commands:
  man             Generate the manual page
  pkgmanagers     Manage package-manager definitions
  stacks          Manage subsystem stack definitions
  subsystems      Create and manage subsystems

There is no install or remove command in the top level list, because the actual package work happens through the subsystems. The note explains it: you run apx SUBSYSTEM COMMAND to use the package manager and environment of a subsystem, and you use apx COMMAND --help or apx SUBSYSTEM COMMAND --help for the available options.

So the four top level commands are all about the machinery rather than the packages. pkgmanagers manages the definitions of the package managers that can be wrapped, stacks manages the subsystem stack definitions, and subsystems creates and manages the subsystems themselves. man generates the manual page, which is also the mechanism the project uses to produce translated documentation.

The credits in the header name distrobox as the project that made this possible, with a link to the 89luca89 repository, which is the hint about the implementation: the managed container is a distrobox, and the special thanks say so plainly.

The repository layout matches the command structure. There is cmd/ for the entry point, core/ and internal/ for the implementation, config/ holding the apx.json configuration, settings/, a distrobox/ directory, man/ for the manual pages, docs/, and a .gitmodules file.

A Go binary built static, with a Makefile that installs more than the binary

The build is a single Makefile and it is worth reading, because the install target does several things at once.

The variables at the top set the installation shape: PREFIX defaults to /usr, DESTDIR to /, and BINARY_NAME to apx. The build rule is a static cross build:

	CGO_ENABLED=0 GOOS=linux GOARCH=amd64 ${GO} build -a -tags netgo -ldflags '-w -extldflags "-static"' -o $@ ./cmd

CGO disabled and the netgo tag together mean the binary does not depend on the host's C library, and the static linker flags strip symbols and link statically, so the result can be copied onto any Linux machine of the same architecture without a runtime dependency. That is a sensible choice for a tool that is going to be installed system wide and used to run other things.

The install target is more interesting than a file copy. It installs the binary into the bin directory, creates an etc/apx directory and installs config/apx.json there, and then it does something the readme does not explain: it rewrites the configuration in place with sed, replacing the path /usr/share/apx/distrobox with the actual prefix, so that a PREFIX install still finds its distrobox payload. It then runs the distrobox install script with the right prefix and moves the resulting binaries into place.

So installing apx also installs a copy of distrobox, and the config is patched to point at wherever it ended up. That is the reason the install target needs sudo and the reason the PREFIX and DESTDIR variables are supported in the way they are.

The manpage target copies the man/ directory into the share/man tree and sets the permissions to 644, the uninstall target removes the binary, the etc/apx directory and the share/apx tree, and there is a separate uninstall-manpages target. The default all target is clean followed by build.

Installing on a distribution that did not write it

The readme spends a long section on using apx outside Vanilla OS, and the framing is deliberate. Apx has been designed as a distro-agnostic tool, allowing it to work with any distribution.

The prerequisites are the honest list. You must have go installed from your distribution's native repositories to compile apx, git installed to clone the repository, either podman, which is suggested, or docker installed, and make installed for the installation.

That podman or docker line is the important one. A managed container needs a container runtime, and apx is not a chroot implementation or a namespace trick of its own. It delegates to distrobox, which in turn needs podman or docker underneath. Anyone planning to use apx on a machine without a container runtime should stop there.

The build steps are four make invocations, and the readme gives them one at a time. Clone the repository recursively and enter it:

``` bash git clone --recursive https://github.com/Vanilla-OS/apx.git cd apx

Build apx using make:

bash make build

Install apx using make:

bash sudo make install

And install the apx manpages using make:

bash sudo make install-manpages ```

The uninstall paths are equally explicit, with make uninstall and make uninstall-manpages.

The custom destination section is the part that shows the Makefile is designed for packagers rather than only for end users. The prefix or installation destination can be changed using PREFIX and DESTDIR, and the examples install apx into the local user directory with make install PREFIX=$HOME/.local, or into a separate root with make install DESTDIR=$HOME/altroot. Since the config file is patched by the install target based on PREFIX, both work without hand editing.

A v3 module path, a small dependency list and community packaging

The Go module manifest is small and tells you the shape of the project.

The module path is github.com/vanilla-os/apx/v3, with the major version in the path, and it requires Go 1.25.0. There are three direct dependencies: the uuid library, a yaml.v2 for the configuration, and the Vanilla OS SDK, pinned to a specific commit hash rather than a version tag, which is a common choice for an internal library that is developed in step with the tool.

The long list of indirect dependencies is mostly the Charm terminal library set, bubbletea, bubbles, lipgloss and their supporting packages, plus go-cli-builder, which is the CLI framework. So apx has a terminal user interface, and it is built on the same stack as a lot of modern Go command line tools.

The translations are handled through Weblate, and the badge at the top of the readme shows the translation status. The procedure for contributing a translated manpage is spelled out in detail, because it involves a build step rather than a text edit: once the translation is complete in Weblate and committed, clone the repository, run go build, create the man directory with the mkdir man and mkdir man1 commands for the language code, then execute the command with the LANG environment variable set to produce apx.1, and open a pull request for the generated manpage. The readme is explicit that the generated file is what goes into the pull request, not the source text.

Community packaging is handled through Repology, and the readme flags the distinction that matters for anyone hitting a bug: the community packages are unofficial, so if there are issues with packaging report them to the respective maintainers, and if there are issues with apx functionalities report them in the project. That is a small but useful thing to know before filing a bug against the wrong repository.

The licence is GPL-3.0, with the COPYING.md file at the root, and the documentation and manpage live at docs.vanillaos.org.

Editorial conclusion

apx suits a team that wants packages and commands to run in isolated containers without writing the container plumbing itself, and a user of another distribution who wants a consistent package interface across several base images. It does not suit a user who wants the system package manager of their own distribution, since apx is explicitly a wrapper around several of them, and it does not suit a machine without podman or docker, which the prerequisites make mandatory. Before installing it, check that your container runtime is present, read the documentation at docs.vanillaos.org, and decide whether the subsystem model fits how you already organise environments.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. Vanilla-OS/apx on GitHub