This is a multi-call binary implementing core NixOS system utilities in safe, portable Rust, replacing some of the Perl and Bash scripts that are generally load-bearing. While those scripts can be replaced through various means such as the Perl-less and Bash-less profiles, those usually change how your system behaves and may yield general instability or breakage, as is the case with the /etc overlay.

This monorepository provides a multi-call ¹ Rust binary to replace some of these fragile scripts, and in some cases utilities already written in Rust. See the motivation section for why we also try to replace Rust code with more Rust code.

The package replaces legacy Bash and Perl scripts that execute on every NixOS system during boot and activation. The multi-call binary design, like BusyBox, reduces binary size and simplifies deployment.

The scope of this program is currently limited by what Nixpkgs permits in terms of replacing legacy solutions.

This project is currently in a "research preview" state. Base rewrites are complete but not yet verified on a real system. Until components are verified through VM tests, do not use them on a production system. Items marked "Awaiting Verification" have not yet been tested on real hardware. Some VM tests will naturally exist, but we cannot know with certainty that everything works as expected until it boots on bare metal.

nixos-core is a multi-call binary invocable either as a symlink:

# Invoke the update-users-groups command
$ update-users-groups /nix/store/...-users-groups.json

Or explicitly as a subcommand:

# Subcommand of update-users-groups
$ nixos-core update-users-groups /nix/store/...-users-groups.json

This usage pattern, like the mono-repo design, is a deliberate choice that allows reusing code and shared patterns without the cognitive overhead of cross-referencing separate projects.

All commands provided by nixos-core are feature-gated, letting you disable commands you don't need at build time and choose which binaries to install and replace. Feature flags work both with cargo and as package arguments when building with Nix:

[(prev: final: {
  nixos-core = prev.nixos-core.override {
    withStage1 = false; # e.g., skip initrd bootstrap
  }
})];

Additional feature flags, also exposed as overridable package attributes, control the behavior of stage 2. These are bootspec, systemd-integration, and full-nixos-init-compat, providing complete compatibility with the pre-existing behavior of Nixpkgs' stage 2. If you are developing a systemd-less NixOS variant but still want to manage stage 2, you can disable systemd-integration while retaining bootspec support. Most of these features are described in detail in the stage2 crate's README.

This project aims to be a safe, independent utility for NixOS and NixOS derivatives such as MicrOS, with the core goals of being fast, portable, and consistent. It is an out-of-tree module to meet those goals without the behavioral changes imposed by Nixpkgs alternatives like Userborn or nixos-init. That is not to say those are fundamentally incompatible with this project, but they are different. There may be room for collaboration in the future.

nixos-core is built with the latest stable Rust available in Nixpkgs, which is 1.94.0 at the time of writing. The Minimum Supported Rust Version (MSRV) is therefore set at 1.94.0, and may change as the language evolves.

• No unsafe code except for unavoidable syscalls (crypt, geteuid)
• Explicit error handling with the ? operator
• Dry-run mode available for all destructive operations

This repository provides a few VM test to verify correct behaviour. Those are rather limited at the time but should provide some amount of guidance for you.

# Run all VM tests that are exposed under `checks`
$ nix flake check

# Run a specific VM tests
$ nix build .#checks.x86_64-linux.boot

You can find the available NixOS VM tests in the nix/vm-tests directory. If you're adding new features, you should add a new test component or some subtests that verify that your code works exactly as expected.

This project is made available under the MIT license, following NixOS/Nixpkgs.