# mitchellh/nixos-config: a macOS host with a NixOS VM, wired through a Makefile

> This repository is one developer's personal NixOS setup, not a template. It shows how a Makefile, a flake and per-machine directories bootstrap a NixOS VM from macOS, and why copying it means learning Nix first.

**mitchellh/nixos-config** — My NixOS configurations.

- Repository: https://github.com/mitchellh/nixos-config
- Website: https://twitter.com/mitchellh/status/1346136404682625024
- Stars: 3,112 · Forks: 248
- Language: Nix
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/mitchellh-nixos-config

## The problem it solves: one developer's split between macOS apps and a Linux dev box

The README states the workflow plainly. The author uses macOS as the host OS and NixOS inside a VM as the primary development environment. Graphical applications (browser, calendar, mail, iMessage) stay on the host; editor, compilation and databases run in the VM. The stated reason is preference rather than performance: the author likes the macOS application ecosystem and Apple hardware, and prefers Linux for development work.

That framing matters when you evaluate the repository. It is not a distribution, a framework or a starter kit. It is the configuration for one person's machine, published so others can read it. The README opens by apologizing to anyone looking for something easy and says the repository is not meant to be a turnkey solution for copying the setup or learning Nix. The author also says he does not claim to be a Nix expert and values having his config work over having it be optimal.

The intended audience is therefore narrow: people who already know what a flake is, who run NixOS somewhere, and who want to see one concrete arrangement of modules, machines and Make targets. If you are looking for a configuration generator, this is the wrong repository, and the README says so before you clone it.

## How the flake, machines directory and Makefile fit together

The repository layout at the top level is small: a Makefile, flake.nix, flake.lock, and the directories lib/, machines/, modules/ and users/. That split suggests the usual NixOS pattern, with flake.nix defining outputs, machines/ holding per-host configurations and modules/ holding reusable pieces, though the README does not document each directory's contents.

The Makefile is where the workflow becomes concrete. It sets NIXNAME to macbook-pro-m1 when uname reports Darwin and to vm-aarch64 otherwise, so the same command produces a different target depending on the machine you run it from. It defines NIXADDR, NIXPORT (22) and NIXUSER (mitchellh) for reaching the VM over SSH, and it bundles SSH options that disable pubkey authentication and host key checking for that connection.

The targets split along the same OS line. On Darwin, switch builds the darwinConfiguration and runs darwin-rebuild switch; on Linux it runs nixos-rebuild switch. The check target evaluates the derivation paths for four configurations: vm-aarch64, vm-aarch64-utm, wsl and macbook-pro-m1. That list is the clearest statement of scope in the repository: two VM hypervisors, a Windows environment and the author's Mac.

## Installing the VM: bootstrap0, bootstrap and the NIXADDR variable

The README's setup guide covers VMware Fusion, with a separate UTM configuration. Download the aarch64 NixOS ISO from the official NixOS download page, create a VM with a SATA disk of 150 GB or more, full graphics acceleration, a shared network with the Mac, and UEFI boot. Boot it, switch to root with sudo su and set the root password to root using passwd.

Before bootstrapping, confirm the disk device. The README says /dev/sda is expected, and that if /dev/nvme or /dev/vda appears instead, the disk was not configured as intended; those device types still work, but the bootstrap0 Makefile task has to be edited to match. Then read the VM's IP address with ifconfig and export it:

```bash
export NIXADDR=<VM ip address>
```

On an ARM VM, select the VM configuration before bootstrapping. The Makefile defaults to the macOS configuration on Darwin, so the README sets this explicitly:

```bash
export NIXNAME=vm-aarch64
```

For UTM, the README says to use vm-aarch64-utm instead. The first bootstrap installs NixOS on the VM disk without applying the rest of the configuration:

```bash
make vm/bootstrap0
```

After the VM reboots, the second command finalizes the customization and should leave you with a graphical dev VM:

```bash
make vm/bootstrap
```

From that point the README says the author stops using Mac terminals, clones the repository inside the VM and works through make test and make switch.

## The macOS half is optional and explicitly unrelated to the VM

The README marks the Darwin setup as optional and unrelated to the VM work, and recommends ignoring it unless you want Nix to manage your Mac too. That setup uses nix-darwin and covers only some aspects of the macOS installation. The author states he does not manage apps, some system settings or Homebrew through Nix, and plans to migrate some of those later.

To use it, you first need the nix CLI with flake support. The README names two installers, nix-installer by Determinate Systems and Flox, without recommending one over the other for this purpose. Once Nix is present, the Makefile's Darwin branch builds .#darwinConfigurations.${NIXNAME}.system and then runs darwin-rebuild switch or darwin-rebuild test with the flake path and NIXNAME.

The separation is deliberate and worth respecting if you copy anything. The VM configuration and the Mac configuration are distinct flake outputs with distinct rebuild tools, and the check target evaluates them separately. Mixing them up is the most likely way to confuse yourself in this repository.

## Where this repository stops being useful to you

The README is candid about the main limitation: it is not a turnkey solution, and copying from it requires learning Nix and NixOS basics. There is no documented rollback procedure, no upgrade guide for the flake inputs, and no support policy. The author says he may not integrate suggested improvements because he prioritizes a working config over an optimal one.

The hardware assumptions are just as concrete. The setup targets Apple Silicon Macs, and the README says the maintained VM configurations do so, with a WSL section covering Windows. The VMware path expects a SATA disk at /dev/sda; other block device types require editing the bootstrap0 task. The web development answer in the README assumes the VM's IP rarely changes and that software in the VM listens on 0.0.0.0 rather than loopback. None of that is a defect, but each item is a place where your environment can differ from the author's and the repository will not adapt itself.

If you want a configuration generator, a shared community template or a supported product, this is the wrong tool. It is one person's working setup, published as-is.

## Alternatives: nix-darwin for the Mac side and a plain NixOS install for the VM side

The clearest alternative in the README is the split this repository already makes. For managing macOS with Nix, the README points to nix-darwin as the underlying project, which is the same tool this repository uses for its Darwin configuration. If your interest is only in declaratively managing a Mac, nix-darwin is the thing to read, and this repository is one example of using it rather than a replacement for it.

For the VM side, the alternative is a plain NixOS installation with your own /etc/nixos/configuration.nix, which is what the NixOS installer produces and what the search questions about configuration file location refer to. That path gives you a single machine definition and no flake, no machines directory and no Makefile indirection. The difference in approach is that this repository centralizes several machines (two VM hypervisors, WSL, one Mac) behind one flake and a set of Make targets, while a plain installation keeps one host and one file. If you only ever run one NixOS machine, the extra structure here buys you nothing.

A third option, if you want Nix without adopting someone else's layout, is to install Nix with one of the two installers the README names and build your own flake from scratch. That is more work up front and avoids inheriting the author's choices.

## Maintenance, licence and what upgrading actually costs

The repository is not archived, and the last push was on 2026-09-23, so it is current as of this writing. That said, the README gives no upgrade instructions for flake.lock, no changelog and no release history; the recent releases list is empty. Updating means running nix flake update yourself and rebuilding, then dealing with whatever breaks in the modules, and the Makefile's check target is the closest thing to a test suite: it runs nix flake check --all-systems --no-build and evaluates the derivation paths for the four configurations.

The MIT licence applies to the repository. That permits reuse and modification with the licence and copyright notice retained, but it says nothing about the software the configuration installs, and it offers no warranty. Because the repository contains one person's machine definitions, licence permission to copy the Nix expressions is not the same as support for the result.

The practical cost of adopting any of it is the cost of reading Nix. There is no versioned interface here, no deprecation policy and no compatibility promise, so every upgrade is a manual review against your own machines.

## Conclusion

Adopt this repository as a reading reference if you already run NixOS and want to see how a flake, a machines directory and a Makefile fit together, especially if you work on macOS with a Linux VM. Do not adopt it as a starting template if you have not written Nix before; the README says outright that it is not a turnkey solution and that copying it requires the basics of Nix and NixOS. Before anything else, verify that your disk appears as /dev/sda inside the VM, because the bootstrap0 Makefile task targets that block device, and check whether you need NIXNAME=vm-aarch64-utm instead of the default vm-aarch64.

## FAQ

### Where is the NixOS configuration located in mitchellh/nixos-config?

The repository keeps its definitions in flake.nix at the top level, with per-machine configurations under machines/ and reusable pieces under modules/, lib/ and users/. A standard NixOS install instead keeps a single configuration.nix under /etc/nixos, but this repository does not use that layout.

### How do I apply a NixOS configuration change in mitchellh/nixos-config?

The Makefile provides make test to build and test the configuration and make switch to activate it. On Darwin the switch target builds the darwinConfiguration and runs darwin-rebuild switch; on Linux it runs nixos-rebuild switch with the flake and NIXNAME.

### What are the downsides of using mitchellh/nixos-config?

The README states the repository is not a turnkey solution and that copying from it requires learning the basics of Nix and NixOS. It also documents no rollback procedure or upgrade guide, and the author says he values a working config over an optimal one, so suggested improvements may not be integrated.

### Does mitchellh/nixos-config work on Apple Silicon Macs?

Yes. The README says the author has used an Apple Silicon Mac full time since November 2021 with this setup, using VMware Fusion, and the repository also includes a UTM configuration.

## Sources

- [Issues](https://github.com/mitchellh/nixos-config/issues)
- [License: MIT](https://github.com/mitchellh/nixos-config/blob/main/LICENSE)
- [mitchellh/nixos-config on GitHub](https://github.com/mitchellh/nixos-config)
- [Project website](https://twitter.com/mitchellh/status/1346136404682625024)
- [README](https://github.com/mitchellh/nixos-config/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mitchellh-nixos-config