Skip to content
Frostyard docs

Nix

The Nix extension adds the Nix package manager and its multi-user daemon to a Frostyard bootc image. Use it when you want Nix packages and profiles next to the software the image ships. Every image carries the extension’s definition, switched off. The extension itself is not in the image: Updex turns it on and downloads it.

Before you start

Section titled “Before you start”

You need:

  • A Frostyard bootc image. Every image built on Base has systemd-sysext and frostyard-updex.
  • Root access to enable, update, and remove the extension.
  • Network access to https://repository.frostyard.org/ext/nix/, and to the sources your Nix expressions fetch.
  • Free space in /var for the image and for the Nix store and profiles. The store grows with each package and profile you add.
  • The user names you will add to the nix-users group.

Nix has no published test results on Frostyard images yet. Try it on a machine you can spare first.

Enable Nix

Section titled “Enable Nix”

See what Updex found, then enable the feature and download it now:

Terminal window
updex features list --component=nix
sudo updex features enable nix --now

nix appears as a component, with its feature disabled. The enable command downloads the image, checks its checksum and signature, links it, and refreshes the merge.

Check that the image is merged, the mount is up, and the daemon runs:

Terminal window
systemd-sysext status
systemctl status nix.mount nix-daemon.service

systemd-sysext status lists nix. nix.mount puts /var/lib/nix at /nix, and the daemon is bound to that mount, so it stops when the mount fails.

If enable --now exits with a refresh error (refresh_error in JSON), the download worked, but the activation did not. If the output says activation did not finish, the extension is merged, but users and groups can be missing: reboot. Otherwise the merge state is unknown: reboot. A sudo systemd-sysext refresh by hand does not create users and groups. Then run the two checks above again.

Use Nix

Section titled “Use Nix”

Client access is opt-in. The extension recreates Debian’s nix-users group and adds nobody to it. Add your account:

Terminal window
sudo usermod -aG nix-users USER

Replace USER with your user name. Log out and in again: the new session has the group. This grants access to the daemon socket. It does not grant Nix trusted-users privileges.

Check the command and the store:

Terminal window
command -v nix
ls /nix/store

Every user can read the store. Only the nix-users group can reach the daemon socket, and the daemon does the writes.

Multi-user builds run as nixbld1 to nixbld10, all members of the nixbld group, at the UIDs and GIDs that the official Nix installer uses. Profiles and garbage-collection roots live under /var/lib/nix/profiles and /var/lib/nix/gcroots, which you also see under the /nix mount. Both directories are world-writable, so any user can create a profile or register a root.

The Nix configuration lives in /etc/nix. The extension keeps a default copy in /usr/share/factory/etc and copies it into /etc at boot when /etc/nix is missing. Edit the files in /etc/nix; your edits survive reboots and updates. The copy happens only once, so a later update with new Nix defaults does not change an existing /etc/nix.

Update and remove

Section titled “Update and remove”

An update refreshes the merged /usr while the daemon runs. Let running builds finish before you update by hand. Your store, profiles, and roots in /var/lib/nix stay.

Remove Nix now:

Terminal window
sudo updex features disable nix --now --force

Updex unmerges all extensions on the host, deletes the Nix image, and merges the rest again. The mount unit and the daemon go. /var/lib/nix stays, with every store path and profile you built. Reboot when the command finishes. Without --force, Updex refuses while the image is merged.

Roll back

Section titled “Roll back”

Roll back with sudo updex features rollback nix. It takes effect at the next boot. Updex then holds updates until a newer version is published. To stop future updates instead, run sudo updex features disable nix. /var/lib/nix stays either way. See Roll back.

See Manage system extensions for the update check, the timer, and plain disable.

Troubleshooting

Section titled “Troubleshooting”
Symptom Check Fix
A Nix command fails with a permission error id -nG USER and systemctl status nix-daemon.service Add the user to nix-users with sudo usermod -aG nix-users USER, then start a new login session.
nix-users is missing getent group nix-users The group comes from usr/lib/sysusers.d/nix.conf, and the rules are applied at boot. Reboot and check again.
The daemon is not running systemctl status nix.mount nix-daemon.service The daemon is bound to nix.mount. Check the mount and /var/lib/nix, then start nix.mount.
/nix/store is empty or missing systemctl status nix.mount The bind mount is not active. Start nix.mount, or reboot.
/etc/nix is missing ls /etc/nix The copy runs at boot. Reboot after the merge and check again.
enable --now exits non-zero after the download The output shows Error: sysext refresh failed (refresh_error with --json) If the output says activation did not finish, reboot. Otherwise reboot too: a refresh by hand does not create the extension’s users and groups. Then check systemd-sysext status.

What ships

Section titled “What ships”
Item What you get
Package nix-setup-systemd, which brings the Nix binaries and the daemon units
Version The image file name carries the nix-setup-systemd version, plus a +rN snosi revision when one is set
Image file nix_<version>_<os>_<arch>.raw.zst; .raw.xz, .raw.gz, and .raw also work
Download From https://repository.frostyard.org/ext/nix/, signature required (Verify=true), into /var/lib/extensions.d/
Command /usr/bin/nix
Services nix.mount, nix-daemon.socket, and nix-daemon.service, enabled by 40-nix.preset. 10-nix.conf upholds nix.mount and nix-sysext-setup.service, which pulls in the daemon units at boot
Mount /nix is a bind mount of /var/lib/nix
Users and groups nix-users with no members, and nixbld with nixbld1 to nixbld10
Configuration A default /etc/nix, held in /usr/share/factory/etc
State /var/lib/nix: the store, profiles, and garbage-collection roots

Each build checks that the Nix binary, the user rules, nix-daemon.service, nix.mount, nix-sysext-setup.service, the boot drop-in, and the factory nix.conf are present. A build that is missing one fails. The image is an overlay, so a later Base can break an older Nix image.

See also

Section titled “See also”

Sources

Section titled “Sources”

Reviewed 2026-10-27; Updex facts reviewed 2026-10-30. snosi commit b2858ca0222814c395cf8248db98f3e096d57dc9; Updex v2.1.3 commit 2661e987faac986f2594d1d9bbbadf1bf3053f5b.