EmergentMind's nix-config is a multi-host NixOS flake you are meant to read, not clone

What this repository is actually for

The repository describes itself as a continually evolving multi-user, multi-host NixOS configuration, and the README is unusually direct about its purpose. It says the configuration is written perhaps as more of a reminder for the author than for the reader, and that it will serve you best as a reference, learning resource, and template for crafting your own configuration.

That framing matters, because it tells you how to read the code. This is not a distribution to install, it is a worked example to take apart. The README is direct that you must experiment and learn as you go to create a nix environment that suits your needs, and it points to a YouTube channel, a Discord server and a website as further resources.

The tone is literary, and the opening is a small piece of theatre rather than documentation. It describes finding a cairn in the fog, and it opens with a command that refuses to identify its user:

$ whoami
error: entity unknown or undefined

The requirements section is the most operationally useful part of the README for anyone considering adoption, and it is four lines long: patience, attention to detail, persistence, and more disk space. That last one is the concrete constraint. A configuration with encrypted btrfs volumes, impermanence and multiple images wants real disk.

There is also a separate repository, nix-config-starter, described as a stripped down and simplified version of this one, and the README is careful to say it does not have feature parity. That pointer is the honest entry point for most people.

The structure rule: core is a hard rule and everything else is optional

The directory layout is where this configuration's design becomes legible, and the README states the organising principle more than once: if something is not core, it is optional.

At the top, flake.nix is the entrypoint for hosts and user home configurations, and it also exposes a devshell for manual bootstrapping tasks via nix develop or nix-shell. The hosts directory holds the NixOS configurations, reachable with sudo nixos-rebuild switch --flake.#<host>. Under it, common holds shared configurations consumed by the machine specific ones, and within common there are three tiers. core holds configurations present across all hosts, and the README calls that a hard rule. optional holds configurations present across more than one host. users holds host level user configurations present across at least one host, with a keys subdirectory per user holding public keys that are symlinked into ~/.ssh.

Then nixos holds the machine specific configurations, and the names make the intent plain. There is genoa, a ThinkPad E15, ghost, described as the primary box with a Ryzen 9 5900XT and an RX 9070XT, and microvms directories under it for microvm environments that run on ghost. There is grief, a lab Qemu VM, gooey, labelled stage x, guppy, a remote install lab Qemu VM, gusto, a theatre mini PC with an N95, and iso, a custom NixOS ISO that folds in quality of life configuration for installations and recovery.

The home directory mirrors the same shape for Home-Manager configurations, which the README says are built automatically during host rebuilds, with common, optional and per-user, per-host directories. The microvms directory holds ephemeral agent sandbox environments, and the README notes that its structure intentionally mimics nix-config while staying separate. A lib directory holds a custom library used throughout to make import paths more readable, accessible as lib.custom, and modules holds custom modules split into home and hosts, with the hosts side split into common, darwin and more.

The overlays and pkgs directories, and a checks directory at the top level, complete the layout.

Secrets, encryption and impermanence

Three of the feature highlights are the parts that make this configuration more than a list of packages.

The first is secrets management via sops-nix and a private nix-secrets repository that is included as a flake input. The private repository is not part of this one, which means the design separates the encrypted secrets from the code that consumes them, and the flake input is how the two are joined. Anyone adopting this needs to create their own secrets repository and point the input at it, and the README's structure quick reference does not document the mechanics of that, so it is the first place to look when you start.

The second is declarative, LUKS-encrypted btrfs partitions via disko. Declarative here means the on-disk partitioning and encryption are described in the configuration rather than performed by hand, so a rebuild can recreate them, and btrfs is the filesystem that makes the next feature work.

The third is impermanence, described as files that are not explicitly persisted are deleted on reboot. This is a large behavioural commitment for a laptop. The model is that state lives outside the system partition and is re-established at boot, which is fast and reproducible, and that anything you forget to declare is gone. For a configuration whose state is managed this deliberately, that works well. For a machine where you keep things in /home without thinking about it, it is a data loss waiting to happen, and it is worth understanding the mechanism before you adopt it rather than after.

The README also lists automated borg backups and automated remote bootstrapping of NixOS, the nix-config and the private nix-secrets, which is what makes the multi-host story work when a machine needs to be rebuilt from scratch.

YubiKey handling across login, sudo, ssh and disk decryption

The authentication feature list is unusually specific, and it is worth reading line by line because each line names a different mechanism.

The configuration handles multiple YubiKey devices and agent forwarding for touch-based or passwordless authentication during login, sudo, ssh, git commit signing and LUKS2 decryption. Those five contexts are the ones that matter in a real workstation, and covering all of them from one configuration is the point.

The agent forwarding detail is the part that distinguishes a workable setup from an aspirational one. When the YubiKey is used over SSH, the challenge has to reach the key physically attached to your local machine, and forwarding the agent is how that happens. A configuration that only handles local login leaves you typing passphrases over SSH, which is where most people give up on hardware keys.

The git commit signing entry is the other one worth calling out. Signing commits with the same key you use for disk decryption means the private key has to be reachable in the contexts where you commit, which is exactly what the agent forwarding is for.

The microvm feature, automatic micro-vm sandboxing for agents, connects back to the microvms directory in the structure. The README describes those as ephemeral agent sandbox environments with a structure that mimics nix-config while staying separate, and the microvm environments run on the ghost host. This is a trend worth noting: a personal machine configuration that treats AI coding agents as workloads deserving their own isolated virtual machines, rather than as processes with access to your home directory.

The justfile is where the workflow is actually written down

The repository ships a justfile rather than documenting commands in prose, and reading it is the fastest way to understand the intended workflow.

The check recipe is the one to start with. It sets NIXPKGS_ALLOW_UNFREE=1 and REPO_PATH, then runs nix flake check with the --impure, --keep-going and --show-trace flags, and it does the same inside the nixos-installer directory. The --impure flag is what allows the repository path to be passed in as an environment variable, and --keep-going means the check reports every failure rather than stopping at the first, which is the behaviour you want when a config has several independent problems.

The rebuild recipes are layered on top. There is rebuild, which calls rebuild-host for the given host and then rebuild-post, and rebuild-full, which does the same and then runs the check. The rebuild-post step is where the post-build verification lives, and the README's comment for it names the check as being for whether sops is running properly afterwards, which is a sensible thing to verify since the whole secrets chain depends on it.

The update recipes are separate from the rebuild recipes, and the separation is deliberate. update takes a host and an input and runs nix flake update with a --timeout 5 flag. The upgrade recipe is defined as update followed by rebuild, which is the standard flake workflow of refreshing inputs and then rebuilding against them.

There is a rebuild-pre recipe that chains several update steps for commonly changing flakes, including nix-assets, emergentvim, the nix-index database and introdus, before running git add --intent-to-add and updating the neovim flake.

The default recipe is just @just --list, which is a small courtesy that makes the tool self-describing.

The mirrors, the moving parts and where the project is heading

Two things in the README indicate that this is a project in flux rather than a finished artefact, and both are worth knowing before you invest time in it.

The first is the April 30, 2026 note at the top. It says the nix related repositories by EmergentMind on GitHub are now mirrored from repositories of the same name at codeberg.org, that depending on which domain you visit, the commit signing before and after the change may show as unverified, and that many of the reference URLs throughout may still point back to GitHub until the author gets around to correcting them. The default branch is dev and there are no GitHub releases, so there is no tagged version to pin.

The second is the note about the Home concept being in flux. The README says that as of September 2025 the author has been rethinking how to handle multiple users, that the concept for Home is in a bit of flux, that some of the changes are reflected in the structure listing, and that the diagram shown is the iteration prior to those changes until there is a better idea about the outcome and how to represent it visually. The link to the anatomy documentation and the concept diagram are how you are meant to understand the design intent, and the README points to an article and a video titled Anatomy of a NixOS Config for the design concepts and constraints.

The consequence for a user is that the structure you read may not be the structure the author intends, and the multi-user model is the part under active rethinking. If you are adopting a multi-user setup, that is the part of the design to watch.

What is stable is the feature set itself, the directory conventions, and the workflow in the justfile, and those are the parts worth learning from.

Editorial conclusion

Adopt this configuration as a reference and a learning resource if you are setting up NixOS across more than one machine and want a working example of disko, sops-nix, impermanence and host-specific overlays rather than assembling those pieces yourself. Do not adopt it wholesale as your own starting point if you want a small, comprehensible setup, since the requirements list asks for patience, attention to detail, persistence and more disk space, and the author points at a separate nix-config-starter for a stripped down version. Verify first that you can create and maintain a private nix-secrets repository as a flake input, that the machine-specific host entries under hosts/nixos match the hardware you actually own, and that the LUKS and impermanence assumptions hold for the data you keep.

Frequently asked questions

Official sources

1. EmergentMind/nix-config on GitHub
2. Issues
3. License: MIT
4. Project website
5. README