StageX overview¶

Understand StageX's package model, published images, pallets, and core design choices.

What StageX is¶

StageX is a Linux distribution and build system for verifiable infrastructure. It packages full-source bootstrapped, reproducible system components as OCI images that can be pulled, verified, composed, and independently rebuilt.

StageX is designed around a narrow goal: eliminate single points of failure in the software supply chain while keeping the system understandable enough to rebuild and verify.

That goal shows up in three ways:

StageX packages are distributed as immutable OCI images.
StageX package definitions live in source and are built from Containerfiles.
StageX considers a package reproducible only when the artifact is deterministic, and both the package definition and the in-tree toolchain used to build it are full-source bootstrapped.

In other words, software must be both full-source bootstrapped and reproducible to be included in StageX.

For a deeper technical explanation of the project goals and design, read the StageX whitepaper.

What StageX provides¶

StageX provides a source tree, a package set, and published OCI images.

The source tree contains the package definitions and build logic. The package set contains bootstrapping components, core system packages, reusable build environments, and higher-level user packages. The published OCI images let users build applications or compose systems without first rebuilding all of StageX locally.

The published images are useful for normal application builds. Before relying on them, you can verify image signatures to check that maintainers signed the artifacts you are using. Rebuilding StageX from source is useful when you want to independently verify that the published images match the source and build process.

Package groups¶

StageX packages are organized into package groups:

Bootstrap packages build the trust base from Stage0 through the early bootstrap stages.
Core packages provide the base toolchain, C library, build tools, language runtimes, shells, and common libraries.
Pallet packages provide reusable build environments for applications and downstream packages.
User packages provide higher-level tools, services, libraries, kernels, runtimes, and applications.

Each package is an OCI image. Package names include the group prefix, such as core-musl, pallet-rust, or user-containerd.

Pallets and application builds¶

Pallets are the easiest way to use StageX in an application build. A pallet is a prebuilt StageX build environment for a language or toolchain ecosystem.

For example, the quickstart uses pallet-rust as the build stage:

FROM docker.io/stagex/pallet-rust@sha256:2fbe7b164dd92edb9c1096152f6d27592d8a69b1b8eb2fc907b5fadea7d11668 AS build

The build stage contains the compiler and supporting tools. The runtime stage can then copy only the final application artifact into a minimal image.

Available pallets include build environments for:

C/C++ with Clang or GCC
CGo
Cython
Go
Lua and LuaRocks
Node.js and npm
PHP and Composer
Python
Rust
Solidity

For a current list, browse the StageX package index.

Where images are published¶

StageX images are published to:

Use pinned digests in builds whenever possible:

FROM docker.io/stagex/pallet-rust@sha256:2fbe7b164dd92edb9c1096152f6d27592d8a69b1b8eb2fc907b5fadea7d11668 AS build

The same image may also be available from Quay:

FROM quay.io/stagex/pallet-rust@sha256:2fbe7b164dd92edb9c1096152f6d27592d8a69b1b8eb2fc907b5fadea7d11668 AS build

Package source definitions live in the StageX source repository.

Design choices¶

The choices below support the StageX integrity model while also improving different parts of the system.

OCI images and Containerfiles¶

StageX uses Open Container Initiative (OCI) images as its native package format, and it defines those package images with Containerfiles. Packages are built, signed, distributed, verified, and composed as OCI images rather than being installed by a traditional package manager.

This matters because OCI gives StageX:

Immutable package artifacts: A package image is addressed by digest and can be verified before use.
Container-native composition: Packages can be combined with normal COPY --from=... container workflows.
No install scripts at runtime: Verification and unpacking are the primary operations; arbitrary package install scripts do not run on the target system.
Existing distribution tooling: Registries, signatures, image policies, mirroring, and runtimes already exist in the OCI ecosystem.
Runtime diversity: OCI-compliant images can run across different runtimes, reducing dependence on one implementation.

Containerfiles are the package definition language for this model. They are not required by the OCI specification itself, but they are the familiar and inspectable way StageX describes how each package image is assembled.

Using Containerfiles also supports reproducibility work because inputs, build stages, copied artifacts, and final filesystem contents are visible in one place. StageX still requires discipline around pinned sources, network isolation, fixed timestamps, and deterministic output; the Containerfile format does not provide those guarantees by itself.

In the current documentation, the starter workflows use Docker. The design target is broader OCI compatibility, but Docker is the supported path in these docs for now.

LLVM and Clang¶

StageX uses LLVM/Clang as its primary modern toolchain. Clang is a native cross-compiler: one Clang installation can emit code for multiple targets when the correct target triple and sysroot are provided.

That helps StageX reduce the number of separate compiler stacks it has to maintain. Fewer parallel toolchains mean less duplicated build logic, less maintenance surface, and fewer places for toolchain-specific behavior to drift.

The same property also helps with C library flexibility. Because Clang can target a different sysroot, StageX can build comparable artifacts against different libc implementations, such as musl and glibc. That makes it easier to identify compatibility issues and benchmark workload-specific performance differences without changing the whole compiler stack.

LLVM is also modular. StageX can use LLVM tools such as Clang, compiler-rt, libunwind, and related utilities as a coherent toolchain rather than stitching together unrelated compiler components.

mold linker¶

StageX uses mold as part of its linker toolchain. The StageX profile exports LD=ld.mold, and core LLVM builds are configured to use mold.

The practical reason is build performance: linking large packages can be expensive, and a faster linker shortens rebuild cycles. That matters for a project where maintainers and users are expected to reproduce packages rather than only consume published binaries.

mold is not a substitute for reproducibility, bootstrapping, or signature verification. It is a toolchain choice that supports the broader workflow by making repeated builds less painful.

musl by default¶

StageX uses musl as the default C library. musl has a smaller codebase than glibc, avoids many historical compatibility layers, and tends to provide consistent behavior across platforms.

For StageX, that supports the minimalism goal: smaller trusted computing base, fewer moving parts, and less code to audit. StageX can still build artifacts for GNU/glibc compatibility where needed, and that libc flexibility is part of the design, but musl is the default foundation for the minimal path.

mimalloc allocator¶

StageX uses mimalloc as the default allocator with musl. musl's allocator is small and simple, but it can be a poor fit for some multi-threaded workloads.

mimalloc addresses that tradeoff by improving allocation performance while keeping the musl-based system model. The result is a default stack that keeps musl's minimal and auditable C library while avoiding some allocator performance costs.

Minimal runtime images¶

StageX packages are built as FROM scratch style images containing only the installed package output. Application images can follow the same pattern: build in a pallet image, then copy only the final static binary into a minimal runtime image.

This is why the quickstart ends with a scratch runtime image. The build stage contains the toolchain; the runtime stage contains the application.