Misterio77/nix-starter-configs: NixOS and home-manager flake templates, minimal and standard

The gap nix-starter-configs fills between the NixOS manual and a working flake

The NixOS manual explains options. It does not hand you a repository that already wires a flake to a system configuration and a home-manager configuration with the same inputs, and that is the step where most first attempts stall. This project is two directories, minimal and standard, each a flake template you pull into an empty git repository. The minimal version targets people who have never used flakes, or who are moving a simple configuration over. The standard version targets people who already use flakes and want boilerplate for overlays, custom packages and their own module directories. The audience is narrow on purpose: you need a NixOS system, live or installed, or an existing distribution with Nix and home-manager on it. The README notes the same approach works on Darwin if you ignore the nixos-* commands.

Minimal versus standard: what each template actually contains

The difference is directory shape, not features you toggle. Minimal gives you a NixOS configuration at nixos/configuration.nix, reachable through nixos-rebuild --flake ., and a home-manager configuration at home-manager/home.nix, reachable through home-manager --flake . That is the whole surface. Standard keeps both of those and adds a pkgs directory for custom packages, an overlay directory, and module directories at modules/nixos and modules/home-manager. The README states that the standard configurations should use your overlays and custom packages out of the box, and that a package built this way is reachable as nix build .#package-name. The repository layout confirms the split: the top level holds flake.nix, flake.lock, minimal/ and standard/ side by side, so the two templates are independent trees rather than one tree with a flag. If you pick minimal and later want overlays, you are copying directories by hand rather than changing a setting.

Installing the template and applying a first configuration

The README assumes a booted NixOS system, live or installed, and links to the NixOS download page. It also says you can use Nix and home-manager on an existing distribution and simply skip the nixos-* commands. Start by creating the repository that will hold your configuration, then opt into the two experimental features the flake commands need. Setting NIX_CONFIG this way is scoped to the current shell session.

cd ~/Documents
git init nix-config
cd nix-config
export NIX_CONFIG="experimental-features = nix-command flakes"

With the features enabled, pull one of the two templates. The fragment after the # selects minimal or standard, and the command writes the template files into the current directory.

# For minimal version
nix flake init -t github:misterio77/nix-starter-config#minimal

# For standard version
nix flake init -t github:misterio77/nix-starter-config#standard

Before rebuilding, move your existing configuration in. The README says to add what you currently have under /etc/nixos/ into nixos, usually configuration.nix and hardware-configuration.nix, and what you have under ~/.config/nixpkgs into home-manager. If you do not have a hardware-configuration.nix yet, mount your partitions at /mnt and generate one. Then open flake.nix and fill in everything marked FIXME, which the README describes as required, and TODO, which it describes as tips or optional extras. Update the lock file so you get current packages and modules, then apply the system configuration, substituting your own hostname.

nixos-generate-config --root /mnt
nix flake update
sudo nixos-rebuild switch --flake .#hostname

If you are still on a live installation medium, the README says to run nixos-install --flake .#hostname instead and reboot. For the home side, the command is home-manager switch --flake .#username@hostname, and if home-manager is not installed you can get it with nix shell nixpkgs#home-manager. The first rebuild is where you find out whether your FIXME values are right; a name mismatch between the flake attribute and your command fails before anything is written.

Running home-manager as a NixOS module changes how you rebuild

The README documents a second arrangement for people who want one rebuild instead of two. You remove the homeConfigurations block from flake.nix and import inputs.home-manager.nixosModules.home-manager into the NixOS configuration, passing extraSpecialArgs and a users attribute that imports your home.nix. The consequence is stated plainly: in this setup the home-manager tool is not installed, and you rebuild the home configuration with nixos-rebuild instead. If you still want the command available, the README shows adding inputs.home-manager.packages.${pkgs.system}.default either to users.users.<name>.packages for one user or to environment.systemPackages globally. This is the part of the template most likely to surprise someone who copied the minimal layout and then switched approaches without reading the module section first.

Passwords, secrets and the parts the README leaves open

The README gives two ways to set a default password. By default, nixos-install prompts for a root password, and after rebooting you add a password to your own account and lock root with sudo passwd -l root. Alternatively you can set initialPassword for your user, change it after rebooting, and pass --no-root-passwd to nixos-install. That is the extent of the guidance. Secret management is not covered: there is no mention of sops-nix, agenix or any other scheme, so if your configuration needs real secrets you are choosing and integrating that yourself. The same silence applies to rollback. The README does not document reverting a generation, so the safety net you get from generations is something you learn from NixOS documentation rather than from this repository. The standard template's module directories are also empty boilerplate; the README points at the maintainer's own nix-config repository for ideas and labels it, in its own words, a place with reproducible dragons. That is a fair warning that the example is a personal configuration, not a reference architecture.

Where the templates stop being the right tool

The README opens with a note that the repository might become slightly out of date as things change fast, and directs readers to the official NixOS and home-manager documentation and to issue 86 for more resources. Take that at face value. Templates copy files once; they do not track upstream option renames, and nothing in the repository updates the files you generated after the initial nix flake init. A configuration that already spans several machines with shared modules, or that depends on a secret-management stack, will outgrow the boilerplate quickly, and the standard template's module directories are placeholders rather than a working multi-host layout. The README's own advice on adding hosts is to organize by hostname and username under the nixos and home-manager directories and to remember to add them to flake.nix, which is manual bookkeeping. If you want a framework that manages that bookkeeping for you, this is not it. The last push to the repository was on 2026-04-24, so the templates reflect the state of the ecosystem at that point, not today's.

Alternatives: hand-written flakes and full configuration frameworks

The obvious alternative is writing flake.nix yourself from the NixOS and home-manager manuals. That is more work up front and it is the path the README implicitly assumes you will take eventually, since it tells you to consult those manuals to make sure you are doing things right. The difference in approach is that a hand-written flake has no boilerplate to delete and no FIXME markers to interpret, but it also has no working example of how inputs flow into a system configuration and a home configuration at the same time. A second alternative is adopting someone's complete personal configuration repository, such as the maintainer's own nix-config, which the README links. That gives you a working multi-host setup with real modules, at the cost of reading and pruning decisions made for someone else's hardware and habits. The templates sit between the two: more structure than a blank flake, far less than a full configuration you would have to untangle.

Licence, maintenance and what an upgrade actually costs

The repository is licensed CC0-1.0, which places the template files in the public domain, so copying them into your own repository and modifying them carries no attribution requirement. That matters for the workflow the README describes, where you git init a fresh repository and commit the template contents as your own starting point. One caveat worth stating without pretending to give legal advice: CC0 is unusual for software and is aimed at the template text and configuration files here, not at the Nix packages your configuration pulls in, which carry their own licences. On maintenance, the last push was on 2026-04-24. There are no releases, so there is nothing to pin and no changelog to read; the unit of change is a commit on main. Upgrading is not a package operation at all. You either re-run nix flake init into a scratch directory and diff the result against your configuration by hand, or you read the repository history and port the changes you care about. Because you own the copied files, nothing forces an upgrade on you, and nothing warns you when an option in your configuration has been renamed upstream.

Editorial conclusion

Adopt the minimal template if you are booting NixOS for the first time or migrating a small configuration to flakes, and the standard template if you already write overlays and custom packages. Do not adopt either as a long-lived dependency: the README states the repository can fall behind upstream NixOS and home-manager, so treat the files as a starting point you own and edit, and check the official manuals alongside them. Before switching, verify that hardware-configuration.nix exists for your machine (generate it with nixos-generate-config --root /mnt if not), that every FIXME marker in flake.nix is filled in, and that the hostname and username in your rebuild command match the attributes the flake exposes.

Frequently asked questions

Official sources

1. Issues
2. License: CC0-1.0
3. Misterio77/nix-starter-configs on GitHub
4. README