pkgx

README

pkgx

The pkgx runtime in pure Go — one static binary that runs any pkgx package on the fly, and works on a literally-empty FROM scratch image.

pkgx is the runtime half of the pure-Go pkgx family; its sibling pkgm is the installer. Both share one backend — bottle resolution, download, FROM scratch closure completion, and loader-aware exec — via the github.com/go-pkgx/bottle package, so there is a single source of truth and no duplication.

Like pkgm it is CGO_ENABLED=0 with no runtime dependencies of its own: no Deno, no curl, no shell — a single ~9 MB binary that materialises each package's full dependency closure on demand and execs it.

Usage

pkgx <pkg>[@version] [arg...]      run a package's program ephemerally
                                   e.g. pkgx node@22 --version
pkgx +<pkg> [+<pkg>...] [cmd ...]  bring packages into the environment and run
                                   cmd with them on PATH + LD_LIBRARY_PATH
                                   e.g. pkgx +git +gnu.org/bash -- ./build.sh
pkgx -h,--help   pkgx -v,--version

# on a FROM scratch image whose only file is the pkgx binary:
$ pkgx node@22 --version
v22.x.x
$ pkgx +git +gnu.org/bash -- sh -c 'git --version'
git version 2.x.x

Environment

• PKGX_DIR — bottle store (default ~/.pkgx)
• PKGX_DIST — bottle source (default oci://ghcr.io/go-pkgx/packages, the signed registry; set https://dist.pkgx.dev for the full unsigned upstream pantry — pair with PKGX_VERIFY=0)
• PKGX_VERIFY — verify bottle signatures, fail-closed (default on; set 0/false/no/off to disable)

By default pkgx <pkg> fetches from the signed registry and verifies each bottle's signature before running it — no env needed.

~/.pkgx/config.hcl2

Rather than exporting the PKGX_* (and OCI auth) variables every time, set their defaults declaratively in ~/.pkgx/config.hcl2. It is a small HCL2 file of top-level attributes; a real environment variable always overrides a value set here:

# ~/.pkgx/config.hcl2 — defaults for the go-pkgx tools.
# A real environment variable always overrides a value set here.
PKGX_DIST   = "oci://ghcr.io/go-pkgx/packages"  # signed registry (default)
PKGX_VERIFY = true                               # fail-closed signature check
# PKGX_DIR    = "/opt/pkgx"
# PKGX_PANTRY = "https://raw.githubusercontent.com/pkgxdev/pantry/main/projects"
# OCI_TOKEN   = "..."                            # private-registry credentials

Values may be strings, booleans, or numbers. A missing file is ignored; a malformed one is reported once on stderr and otherwise ignored (the tools fall back to environment variables and built-in defaults).

Design

Pure Go, cgo disabled — cross-compiles to six 64-bit targets (linux & darwin, amd64/arm64, plus riscv64 & ppc64le). On FROM scratch it reads each bottle's ELF DT_NEEDED to auto-complete the implicit libc/gcc closure the pantry graph omits, then execs through the pkgx glibc loader so the program and its children resolve. BSD-3-Clause.

Documentation

Overview

Command pkgx is a dependency-free, pure-Go implementation of the pkgx runtime: it runs packages on the fly, materialising each one's full dependency closure on demand — from the signed OCI registry oci://ghcr.io/go-pkgx/packages by default, verifying each bottle's signature (fail-closed) — with no runtime deps of its own (a single CGO_ENABLED=0 binary that works on a `FROM scratch` image). Point PKGX_DIST at the unsigned upstream (https://dist.pkgx.dev) with PKGX_VERIFY=0 for the full pantry.

It shares its whole bottle backend — resolution, download, FROM-scratch closure completion, and loader-aware exec — with pkgm via the github.com/go-pkgx/bottle package, so there is one source of truth.