matrixOS is a Gentoo-based Linux distribution that blends the power and customizability of Gentoo with the reliability of OSTree atomic upgrades. It leverages OSTree to provide Atomicity and Immutability guarantees, ensuring that updates are applied entirely or not at all, and the base system remains read-only to prevent accidental damage.
It comes with Flatpak, Snap, and Docker ready to go out of the box.
Our two main goals are:
- Reliability: Providing a stable, immutable base system through OSTree, which allows for atomic upgrades and rollbacks.
- Gaming-Friendly: Shipping with the Steam loader, Lutris, and optimizations to get you gaming on both NVIDIA and AMD GPUs with minimal fuss.
..and our motto is: emerge once, deploy everywhere.
TL;DR: Download from: Cloudflare
GNOME Desktop w/Steam and GNOME Software |
System/OS and Flatpak integration |
OSTree integration |
Coding and AI |
- The OG matrixOS: A Debian-based distribution shipping with Trinity Desktop.
- MatrixOS: An Operating System for Software Defined Controllers.
We need more entropy in this world!
matrixOS is a hobby project created for homelab setups. It is not intended for mission-critical production environments. Everything in this repository is provided "AS IS" and comes with NO WARRANTY.
- Graphics: Latest Mesa and NVIDIA drivers out of the box.
- Cooling: Includes
coolercontroldandliquidctl. - Filesystem:
btrfson/bootand/with zstd compression, auto-resizing on first boot. Includesntfsplusdriver. - Security: UEFI SecureBoot support with easy-to-install certificates.
- Apps: Steam, Flatpak, Snap, AppImage, and Docker available immediately.
Hardware Requirements:
- Architecture: x86_64/amd64 with
x86-64-v3support (AVX, AVX2, BMP1/2, FMA, etc.). - Storage: At least 32GB (64GB recommended) on USB/SSD/NVMe.
Images are available in raw (for flashing) and qcow2 (for VM) formats, compressed with xz.
Trusted Source: Cloudflare
Use these keys to verify the authenticity of images and commits:
- GPG (OSTree, Images):
DC474F4CBD1D3260D9CC6D9275DD33E282BE47CE - SecureBoot Fingerprint:
sha256 Fingerprint=38:02:D7:FC:A7:6F:08:04:9C:7F:D5:D7:AF:9A:24:6C:9B:C2:28:F3:45:99:7B:DF:79:EE:F3:35:0A:81:87:1B
Download the image (compressed with xz) and its .sha256 file, then flash it to your target drive using dd or similar tools.
sha256sum matrixos_amd64_gnome-DATE.img.xz.sha256
xz -d matrixos_amd64_gnome-DATE.img.xz
dd if=matrixos_amd64_gnome-DATE.img.xz of=/dev/sdX bs=4M status=progress conv=sparse,syncThere are two default users:
- root: password
matrix - matrix (UID=1000): password
matrix - LUKS password (if encrypted):
MatrixOS2026Enc
Once booted into matrixOS (e.g., from a USB stick), you can install it onto another drive using the built-in installer.
/matrixos/install/install.deviceIf you are partitioning manually, strict adherence to the following layout is required:
- ESP Partition: Type
ef00| GUID:C12A7328-F81F-11D2-BA4B-00A0C93EC93B - /boot Partition: Type
ea00| GUID:BC13C2FF-59E6-4262-A352-B275FD6F7172 - / Partition: Type
8304| GUID:4F68BCE3-E8CD-4DB1-96E7-FBCAF984B709
After your first boot, run the setup script to configure credentials and LUKS passwords. Run this from a VT or Desktop terminal.
/matrixos/install/setupOS
rebootTo enable Docker: systemctl enable --now docker.
matrixOS supports SecureBoot. You can set it up in two ways:
- UEFI BIOS Enrollment: Enroll the
matrixos-secureboot-cert.pemdirectly into your UEFI BIOS as an Authorized Signature (db). This allows the firmware to trust the matrixOS bootloader and kernel directly. - Shim MOK Enrollment: Use the provided
matrixos-secureboot-mok.derfile to enroll a Machine Owner Key (MOK) via the Shim MOK Manager at first boot. Theshimitself is signed by Microsoft (2011 and 2023), allowing it to run on most hardware, and it then validates subsequent stages using the MOK.
matrixOS uses OSTree for atomic updates.
Update to the latest image:
ostree admin upgradeOr use the experimental vector binary (if available in your image):
vector upgradeIf an update fails, simply boot into the previous entry (ostree:1). To make it permanent:
ostree admin pin 1
ostree admin status # to see the current stateList available branches and switch between them (e.g., from gnome to kde if available):
ostree remote refs origin
ostree admin switch <another_branch>
reboot- Temporary Mutability:
ostree admin unlock --hotfix(resets on upgrade). So that you can runemergeas much as you like (important: switch to a*-fullOSTree branch before doing this). - Permanent Jailbreak: Convert to a standard Gentoo system.
- List available branches:
ostree remote refs origin - Switch to the
-fullbranch:ostree admin switch <branch>-full && reboot - Run the jailbreak script:
/matrixos/install/jailbreak && reboot
- List available branches:
You can build custom versions of matrixOS using the provided dev/build.sh script. The build process is: Seeder -> Releaser -> Imager. Respectively, the directories are: build for Seeder, release for Releaser, and image for Imager.
build/seeders/: Contains the build layers (e.g.,00-bedrock,10-server). Each subdirectory has scripts/configs defining packages and settings for that layer.release/: Configuration for the release process.hooks/: Scripts running at different release stages.services/: Systemd services to enable/disable/mask.- Note:
hooks/andservices/follow theOSNAME/ARCH/SEEDER_NAMEpattern (e.g.,matrixos/amd64/gnome) for branch-specific configs.
image/: Configuration for the image creation process.hooks/: Scripts for partition setup, bootloader install, etc.image.releases: Defines which releases are built into images.
All configuration is centralized in conf/matrixos.conf.
- Project Info: OS name, architecture, git repositories.
- Paths: Directories for logs, downloads, and output artifacts.
- Keys: Paths to GPG and SecureBoot keys lead here.
- Component Settings: Specific configs for Seeder, Releaser, and Imager.
Important: If you fork this repository to customize builds, update GitRepo in conf/matrixos.conf to point to your fork.
Run the build script as root. It handles the entire pipeline.
./dev/build.sh- Resume:
./dev/build.sh --resume - Force specific steps:
--force-release,--force-images,--only-images - Enter a chroot:
./dev/enter.seed <name>-<date> - Clean artifacts:
./vector/vector janitor && ./dev/clean_old_builds.sh
Resource Requirements: x86-64-v3 CPU, 32GB+ RAM, ~70GB Disk.
GNOME 48 currently lacks fine-grained scaling (not getting into details here, but it's fixed in 49). Workaround:
gsettings set org.gnome.mutter experimental-features "['scale-monitor-framebuffer']"If nouveau loads despite NVIDIA drivers being present:
ostree admin kargs edit-in-place --append-if-missing=modprobe.blacklist=nouveau
ostree admin kargs edit-in-place --append-if-missing=rd.driver.blacklist=nouveauThis has been fixed after the 20260216 release. Disable SecureBoot, boot the image
and then upgrade your system. You may need to copy the latest /usr/lib/grub/grub-x86_64.efi.signed to /efi/EFI/BOOT/grubx64.efi or run vector upgrade --update-bootloader.
This is because the image files are stripped off of all the unnecessary development only tools and libraries, including C/C++ headers. You have two options:
- Wait for new images, where vector will be shipped compiled and working out of the box.
- Switch to the
-fullbranch, for example, for the GNOME release:
ostree remote refs origin # shows all the branches available.
ostree admin switch origin:matrixos/amd64/dev/gnome-full && rebootThe current focus is on User Friendliness (Milestone 3) and New Technologies (Milestone 4).
- Rewrite core tooling in Go (
vector) to replace bash scripts. - Implement proper CI/CD pipelines and testing.
- Migrate to
bootcor wrapper on top ofostree+ UKI support, moving away from directostreeusage.
Contributions are welcome!
- Code: helping with the migration to
bootcor improving CLI tools. - Resources: Mirrors for images/OSTree repo and compute power for builds.
- Donations: Please donate to Gentoo Linux.
First-party code is released under the BSD 2-Clause "Simplified" License. Third-party applications retain their respective licenses.