dustinlyons/nixos-config: A Nix Starter Template for macOS and NixOS

The problem this flake template solves

Most Nix configurations are written for one machine and one operating system. The moment you want the same shell, editor and packages on a Mac and on a Linux box, you either copy files and let them drift, or you build a flake with a shared module tree from scratch. This repository is a pre-built version of that second option. The README describes it as configuration for a general-purpose development environment that runs Nix on macOS, NixOS, or both simultaneously, and the author states he uses it daily on a MacBook Pro and an x86 PC.

The intended reader is someone who already accepts Nix and wants a starting point rather than a blank flake.nix. The repository ships a templates/ directory with starter versions of the configuration, so the workflow is fork and edit rather than install and run. If you have never written a Nix expression, the step-by-step instructions will get you to a working machine, but you will still be reading modules to understand what changed.

How the flake, hosts and modules fit together

There is no configuration.nix entry point. The README states this explicitly under its flakes feature: no Nix channels, just flake.nix. That file, together with flake.lock, pins every input, and the lock file is what makes the same revision of nixpkgs reach both machines.

The repository layout is the architecture. apps/ holds the Nix commands used to bootstrap and build the configuration. hosts/ holds host-specific configuration, so each machine gets its own directory. modules/ splits into macOS and nix-darwin, NixOS, and shared configuration, which is where the cross-platform promise is actually implemented. overlays/ auto-loads any file dropped into it, which the README says is mainly used for patches. templates/ contains the starter variants. There is also a tests/ directory and systemd/ at the top level, and CI workflows under .github/ that build the starter template and run Statix lint.

The practical consequence is that a change to a shared module lands on both platforms at once, and a change under hosts/ affects one machine. That is a clean separation, but it also means the shared modules carry the burden of conditional logic for two operating systems. Reading modules/shared before editing it is not optional.

Installing on macOS and applying the first configuration

The README gives a numbered macOS path. It starts with Xcode command line tools, then the official Nix installer:

xcode-select --install

sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install)

After the installer finishes, the README tells you to open a new terminal. The next documented step is enabling flakes and the nix-command experimental feature. The README then has you initialize a starter template, make the apps executable, apply your current user info, choose packages, review your shell configuration, optionally set up secrets, and finally install the configuration. The exact commands for those steps are in the repository README, and they are worth copying from there rather than from memory, because the flags matter.

One constraint deserves attention before you start. The README's disclaimer says installing Nix on macOS creates an entirely separate volume that may exceed many gigabytes. It also notes you can uninstall Nix later using the Determinate Systems uninstaller. If a hidden multi-gigabyte APFS volume is unacceptable on your machine, this template is not the right starting point.

The NixOS path is shorter: burn and use the latest ISO, optionally set up secrets, install the configuration, then set the user password. The README does not document a rollback procedure for a configuration that boots badly.

Secrets, Homebrew and the parts that assume a specific setup

agenix handles secrets, and the README lists SSH, PGP and syncthing keys among the use cases, with a separate section on how to create secrets. This is the least portable part of the template. Age keys and encrypted files are tied to identities you generate, so a fork will not inherit working secrets. The optional secrets step exists precisely because you can skip it on a first run.

Homebrew is managed through nix-darwin and nix-homebrew, which the README describes as a zero maintenance Homebrew environment. On macOS this means the brew state is declarative rather than something you mutate by hand. The trade-off is that adding a formula means editing the Nix configuration and rebuilding, not running brew install. If you prefer to install tools ad hoc, this arrangement will feel like friction rather than convenience.

Emacs is the other opinionated choice. The configuration pulls from the nix-community emacs-overlay and runs in daemon mode, which the README presents as instant startup. There is also a large literate configuration in modules/shared/config/emacs/config.org. If you do not use Emacs, a meaningful share of the shared modules is dead weight you will be maintaining.

Where this template is the wrong tool

The clearest mismatch is scope. This is a full desktop configuration with window management, dock layout, App Store applications and a themed NixOS environment. For a headless server or a single-purpose VM, that is a large surface area to audit for very little benefit. A minimal flake with nixpkgs and a short module list would be easier to reason about.

The second mismatch is maintenance appetite. The README says the flake auto updates weekly if changes do not break the starter build, and CI enforces that for the template. Your fork does not inherit that guarantee. Once you diverge, upstream fixes do not arrive on their own, and merging them into edited modules is manual work.

Third, the macOS volume behaviour is a hard constraint, not a preference. The README is direct about it, even inviting readers who dislike it to turn back. Take that at face value.

Finally, the repository has no releases. There is no versioned artifact to pin, so your reference point is a commit on main. That is normal for a config repository, but it means there is no changelog to read before pulling changes.

How it differs from a plain nixpkgs configuration

The obvious alternative is a hand-written flake that imports nixpkgs, nix-darwin and home-manager directly. The difference is not capability, since the underlying modules are the same. It is the decisions already made for you: which inputs are pinned, how hosts are separated from shared modules, how overlays are auto-loaded, and where secrets live.

A plain configuration typically starts with one machine and grows conditionals as a second platform appears. This template starts from the two-platform assumption, which is why modules/ is split three ways and why the README lists same environment everywhere as a feature. The cost is that you inherit someone else's structure. If your mental model of Nix differs, you will spend the first week moving files rather than writing configuration.

A second alternative is to keep macOS unmanaged and only use Nix on Linux. That avoids the separate volume entirely and removes nix-darwin and nix-homebrew from the picture. You lose the declarative macOS setup, which is the main reason to pick this repository over a smaller one.

Licence and what a fork costs you

The repository is BSD-3-Clause, which permits reuse and modification with the copyright notice and disclaimer retained. For a personal configuration fork, the practical effect is that you can adapt the modules freely and redistribute them if you keep the notice. This is not legal advice, and if you plan to ship the configuration as part of a product, read the licence text in the repository rather than a summary.

The upgrade cost is the part people underestimate. Flake inputs move, and a weekly automated update on the upstream template keeps its lock file current. Your fork's flake.lock is yours to update, and every update can change a package version, a module option or a default. The repository has a tests/ directory and CI that builds the starter template, so the upstream project has a way to notice breakage. Your fork has no such signal unless you wire up the same workflow.

Editorial conclusion

Fork this template if you want a working macOS plus NixOS flake with nix-darwin, Home Manager, managed Homebrew and agenix already wired together, and you are willing to read the modules before applying anything. Do not use it if you only need a single Linux machine, if you dislike the separate APFS volume the official Nix installer creates on macOS, or if you are not prepared to maintain a fork. Before applying, verify that your username and hostname match the values in hosts/, check that the flake evaluates with nix flake check, and confirm which secrets agenix expects, because the README does not document a rollback path for a bad switch.

Frequently asked questions

Official sources

1. dustinlyons/nixos-config on GitHub
2. Issues
3. License: BSD-3-Clause
4. README