updex is a Go SDK and CLI for managing
systemd-sysext
images. It provides the url-file transfer functionality of
systemd-sysupdate on systems such as Debian Trixie that do not ship that
tool. Use the CLI to manage extensions, or import
github.com/frostyard/updex/v2/updex from Go.
Status: stable. The tested host is Debian Trixie, and the v2 series gets the fixes that SECURITY.md names.
Documentation: the user guide on frostyard.org; for maintainers, docs/README.md, with the CLI reference for every command, flag and message.
- Features group transfers. Enable, disable, check and update groups of
sysext images described by standard
.featureand.transferfiles. Features and components - Components. Discover named systemd-sysupdate components alongside the legacy default directory. Components
- Catalogs. Browse and install extensions from a configured sysext catalog, and updex owns every file it generates. Catalogs
- Checked downloads. Verify SHA256 hashes and, by default, a GPG signature
on
SHA256SUMS; retry transient failures and decompress xz, gz and zstd images. Remote manifest format - Rollback and holds. Link an older staged version and hold updates until a newer one is published. Rolling back
- Revisions that need a newer base. A revision that sets
UPDEX_MIN_IMAGE_VERSIONstays staged until the image for the next boot is new enough. Minimum image version - Automatic updates. A systemd timer downloads, verifies and links new revisions, which take effect at the next boot. Automatic updates
- JSON output. One JSON document per command, with progress on stderr, for scripts. JSON output
Download the .deb and checksums.txt from the
latest release, then
verify and install the package:
sha256sum --ignore-missing --check checksums.txt
gh attestation verify <downloaded-artifact> --repo frostyard/updex
sudo apt install ./frostyard-updex_<version>_amd64.debThe checksum detects corruption or truncation. The build-provenance attestation binds the artifact to a tag release built by this repository's workflow, so a checksum served beside the artifact is not the only evidence; it needs the GitHub CLI. The CLI reference lists the rpm, apk and tarball artifacts and the build-from-source steps.
updex features list
sudo updex features enable docker --now
updex features check
sudo updex daemon enableFeatures and components
explains what each command reports. updex components lists the discovered
components, and updex catalog list shows what the configured catalogs offer.
updex needs a systemd-based Linux system with systemd-sysext, and commands
that change system state need root. A compressed EROFS sysext also needs
erofs-utils >= 1.8.5 on the host, because updex reads the image's
extension-release file with dump.erofs without mounting it; all frostyard
sysexts are uncompressed. systemd-sysext.service must be enabled for
sysexts to merge at boot, and the state directories /var/lib/extensions and
/var/lib/extensions.d must exist; a packager or an image build does both. See
the packaging and maintainer guide.
mise install # the pinned tools
make ci # what CI runsThe "Getting started" section of AGENTS.md has the prerequisites,
the build and test targets, and the rest of the gate. make verify runs the
same static checks without writing to the tree, for a read-only review.
- AGENTS.md: the rules for agents and contributors.
- docs/README.md: the decisions, designs, specs and plans.
- CLI reference: every command, flag and message.
- Configuration reference:
.transfer,.featureand.catalogfiles. - SDK API reference: use updex as a Go library.
- SECURITY.md: report a vulnerability privately.
- LICENSE: MIT.