matsya snapshots the exact packages on a machine (apt, dnf, yum, zypper,
apk, pacman and Homebrew) into a reviewable, portable matsya.lock.json.
Then it can:
- 🔁 replay that state on another machine, pulling versions that have
left the mirrors from the distro's archive and checking their hashes;
- 🚨 detect drift:
matsya check exits 1, ready for CI and cron;
- 📦 generate SBOMs (CycloneDX 1.6 and SPDX 2.3) straight from the
lock, byte-for-byte reproducible and without touching the machine.
It's a single ~3 MB static binary that depends on nothing. It reads the
dpkg, rpm, apk, pacman and Homebrew databases itself and has its own HTTPS
client. lock, check, diff and sbom work with an empty PATH. Only
apply calls the system package manager, because installing is its job.
🚀 Quick start
curl -fsSL https://raw.githubusercontent.com/dmdhrumilmistry/matsya/main/install.sh | sh
$ matsya lock
matsya: capturing apt ...
matsya: locked ubuntu-24.04-x86_64 (apt: 744) -> matsya.lock.json
$ matsya sbom -o sbom.cdx.json # CycloneDX (or --format spdx)
$ sudo matsya apply # on another machine: same packages, same versions
$ matsya check # later: has anything drifted?
environment: ubuntu-24.04-x86_64
[apt] 1 extra, 2 changed
+ cowsay 3.03+dfsg2-8build1 (installed, not locked)
~ jq 1.8.1-4ubuntu2 -> 1.8.1-4ubuntu1
matsya: drift detected
cargo install matsya # from crates.io
cargo install --locked --git https://github.com/dmdhrumilmistry/matsya
The installer needs no root: it uses sudo or doas only if the target
directory isn't writable, and otherwise installs to ~/.local/bin. In
Termux it installs the native Android build into $PREFIX/bin.
Release binaries (Linux x86_64/aarch64 as static musl builds, macOS arm64/x86_64,
Android aarch64/x86_64/armv7 for Termux)
come with SHA-256 files and GitHub build provenance attestations:
gh attestation verify matsya-x86_64-linux -R dmdhrumilmistry/matsya
In a container you can copy the binary in, run it, and delete it again.
Nothing it needs ends up in the image or in the lock.
💡 Why matsya
Language ecosystems have had lock files for years. The operating system
underneath usually has a hand-written apt-get install line and hope.
| |
|---|
| 🔒 Real lock files | Exact version, architecture, install reason, holds, dependency graph, repository and signing key for every package, plus the SHA-256 from the signed repo metadata. |
| 🌍 One file, many machines | Your Mac, the CI runner and the Raspberry Pi live side by side as environments (macos-15-aarch64, ubuntu-24.04-x86_64, debian-12-aarch64). |
| 🕰️ Versions that disappeared still install | Falls back to snapshot.debian.org, snapshot.ubuntu.com, Fedora Koji, the Arch Linux Archive or brew extract, and verifies the hash before installing. |
| 🧾 SBOMs you can reproduce | purls with distro= qualifiers (so Grype, Trivy and OSV pick the right advisories), SPDX license expressions, hashes, the full dependency graph. Validated against the official schemas in CI. |
| 🔍 Reviewable | Sorted, deterministic JSON. Re-locking an unchanged machine doesn't touch the file, so git diff shows exactly which packages moved. |
| 🪶 Zero dependencies | One static binary. No Python, no rpm, no sqlite3, no curl. It even reads rpm's SQLite, NDB and BerkeleyDB databases (including uncommitted WAL pages) natively. |
How it compares
| Package list / Brewfile | Pinning (apt-mark hold, versionlock) | Syft / Trivy scan | Nix / Guix | matsya |
|---|
| Exact versions + hashes | ✗ | partial | ✓ | ✓ | ✓ |
| Rebuild on another machine | names only | ✗ | ✗ | ✓ | ✓ |
| Locks the distro packages you already use | ✓ | ✓ | ✓ | ✗ (own package set) | ✓ |
| Drift detection | ✗ | ✗ | diff by hand | ✓ | ✓ |
| SBOM | ✗ | ✗ | ✓ | via tools | ✓, from the lock |
| macOS + Linux in one file | ✗ | ✗ | ✗ | ✓ | ✓ |
The deep dive covers the trade-offs honestly,
including when Nix, snapshot mirrors or image digests are the better choice.
🖥️ Supported platforms
| Manager | Distros | Lock | Apply | Old versions come from | CI-tested on |
|---|
| apt / dpkg | Debian, Ubuntu, derivatives | ✓ | ✓ | snapshot.debian.org, snapshot.ubuntu.com (SHA-256) | Debian 12, 13 · Ubuntu 22.04, 24.04 · arm64 |
| dnf5 / dnf / yum | Fedora, RHEL, Rocky, Alma, Amazon Linux | ✓ | ✓ | Fedora Koji (payload digest) | Fedora · Rocky 8, 9 · Amazon Linux 2 · arm64 |
| zypper | openSUSE, SLES | ✓ | ✓ | no public archive | Tumbleweed |
| apk | Alpine, Wolfi | ✓ | ✓ | no public archive | Alpine · arm64 |
| apt in Termux | Android (Termux) | ✓ | ✓ | no public archive | termux-docker x86_64 · aarch64 |
Beyond the package manager, matsya also records software installed with
pip (and pipx), npm -g, cargo install, go install, gem,
snap and flatpak, executables dropped into /usr/local/bin or
/opt/*/bin that no package owns, and macOS apps outside Homebrew
(including App Store apps). All are read straight from disk; most can be
reinstalled by apply. See docs/ECOSYSTEMS.md.
| pacman | Arch, Manjaro, EndeavourOS | ✓ | ✓ | Arch Linux Archive (SHA-256) | Arch |
| Homebrew | macOS, Linux | ✓ | ✓ | brew extract from homebrew-core history | macOS · Linux |
Every CI run copies the static binary into each distro container and goes
through the full cycle: lock, introduce drift, check fails, apply --prune
repairs, then rebuild a fresh container from the lock. Every run also
does lock, check and sbom with an empty PATH.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
