nixos-anywhere: unattended NixOS installs over SSH

The gap nixos-anywhere fills between provisioning and configuration

NixOS configurations describe a running system. They do not describe how a blank disk becomes that system. Someone has to boot an installer, partition the drive, format it, mount it, run nixos-install, and only then hand the machine over to the configuration that was already written. On a cloud server in another region, that someone is usually a person with a console window open, typing commands they have typed before. nixos-anywhere exists to remove that step.

The audience is narrow but real: engineers who manage machines on a mix of platforms and want one installation path for all of them. The README names cloud servers, bare metal servers such as Hetzner, and local servers reachable over a LAN as equally valid targets. The pitch is identical servers anywhere from the same stored configuration, and the ability to repeat an installation if a machine has to be rebuilt. If you only ever install NixOS interactively on hardware you can physically reach, this tool adds a layer you do not need. If you have ever provisioned a server over SSH and wished the disk layout were part of the repository, it is aimed at you.

kexec, disko and the SSH session that drives them

The mechanism is a sequence, not a daemon. You run one CLI command from a source machine that has Nix installed. That command opens an SSH connection to the target. It then detects whether a NixOS installer is already present. If not, it uses the Linux kexec tool to boot the target into a NixOS installer. Kexec replaces the running kernel without going through the firmware, which is why the target does not need a bootable NixOS image of its own.

Once the installer is running, nixos-anywhere hands the disk work to disko, the Nix community partitioning tool. Disko receives the partition and format description from your Nix configuration and applies it. NixOS is then installed onto the result. Two optional stages follow: installing additional Nix packages and other software, and copying extra files to the new machine. The README lists both as optional, which means the minimal path is disk plus OS and nothing else.

This split matters when something goes wrong. The SSH connection, the kexec step, the disko step and the install step are distinct, and the configuration you write feeds the disko step rather than the whole pipeline. If your partitioning description is wrong, you find out at the disko stage, not after a full install.

Running nixos-anywhere for the first time

The source machine can be any machine with Nix installed, according to the prerequisites, for example a NixOS machine. The repository is a flake, so the documented path is to run it rather than to install a package. The README points readers to the Quickstart Guide for the simplest form of the command, and the exact flags live there rather than in the README itself.

What the README does give is the shape of a run: a source machine with Nix, a target reachable over SSH, and a Nix configuration that describes partitioning, formatting and the NixOS configuration itself. The README states that once the configuration has been created, a single command connects to the remote server, detects whether a NixOS installer is present, uses kexec to boot one if not, partitions and formats the drive with disko, installs NixOS, and optionally installs packages and copies additional files.

What you should see is the tool connecting over SSH, reporting whether it needs to kexec into an installer, then proceeding through partitioning and installation without further input. The README describes the process as unattended once initiated: there is no need to babysit the installation.

For a machine with no operating system at all, the README points to a separate how-to guide for booting first from a NixOS installer image. That path exists so you can pre-configure software and preferences and still build the machine with a single command. The prerequisites also allow a custom kexec image via the --kexec flag, which is the documented route for architectures other than x86-64 and for targets that need a VPN connection before the installer can reach anything.

Where nixos-anywhere is the wrong tool

The README carries a warning in bold: never use a production server as the target, because it will be completely overwritten and all data lost. That is not a caveat bolted onto the documentation, it is the boundary of the tool's purpose. nixos-anywhere commissions a new computer or repurposes an old one after the important data has been migrated. It has no rollback story, no dry-run mode described in the README, and no concept of preserving an existing installation. If your question is how to update the configuration of a machine that is already running NixOS, this is the wrong category of tool entirely.

The hardware constraints are equally blunt. Unless you boot from a NixOS installer image or supply your own kexec image, the target must be running x86-64 Linux with kexec support. The README notes that most x86_64 Linux systems have it, and that a custom image extends kexec to other architectures such as aarch64. When kexec is used, the target needs at least 1 GB of RAM excluding swap. A small VPS below that line will not work through the default path.

Networking is the third constraint. The machine must be reachable over the public internet or a local network, and the README states plainly that wifi networks are not supported. If a VPN is required, you define a custom installer via the --kexec flag that connects to the VPN itself. That is a real amount of work for a laptop on a wireless network, and it is the point at which a different approach is probably cheaper.

How it differs from disko, colmena and deploy-rs

The nearest comparison is disko alone. Disko handles partitioning and formatting from a Nix description, and nixos-anywhere uses it for exactly that. The difference is everything around it: the SSH connection, the kexec boot into an installer, and the install itself. If you already have a machine running NixOS and only want declarative disks, disko is the smaller dependency. If the machine has no NixOS on it yet, disko has nothing to run on.

Colmena and deploy-rs sit on the other side of the line. They deploy configuration to machines that already run NixOS, typically over SSH, and they assume a working system to push to. nixos-anywhere assumes the opposite: no usable system, or one you are willing to destroy. The two are complements rather than substitutes. A reasonable workflow is nixos-anywhere once to create the host, then a deployment tool for every change after that. Choosing between them is not a matter of preference, it is a matter of whether the target already exists as a NixOS machine.

The repository also contains a terraform/ directory alongside src/ and tests/, and terraform appears in the related searches around this project. The README does not document a Terraform provider or module, so anyone looking for that integration should read the directory contents and the linked how-to guides rather than assume a supported interface.

Maintenance, licensing and what a rebuild costs

The repository is not archived, and the last push was on 2026-09-23. Recent releases are 1.13.0 on 2025-11-13, 1.12.0 on 2025-09-17 and 1.11.0 on 2025-06-05. The project is written in Shell, which shapes the maintenance picture: the logic lives in scripts under src/ and scripts/, and the test suite under tests/ is what protects changes to the install sequence.

The licence is MIT, which permits commercial use and modification and requires the licence text to be preserved. That is a permissive arrangement, and nothing in the README suggests any additional restriction. This is not legal advice; read the LICENSE file in the repository if the terms matter to your organisation.

Upgrade cost is mostly configuration cost, not code cost. Because the tool is run through a flake reference, the version you get is the one your flake.lock resolves to, and bumping it is a lock file update. The real work after an upgrade lands in your disko description and your target configuration, since those are the inputs the tool consumes. A change to how partitioning is expressed will surface as a failed install on a machine you were about to wipe, which is a better place to find it than on a machine already in service. The project is supported by Numtide, and the README directs questions to a Matrix room.

Editorial conclusion

Adopt nixos-anywhere if you are commissioning new machines or wiping old ones and want the disk layout and the OS installed from one pre-written configuration. Do not point it at a running production server: the README states the target will be completely overwritten and all data lost. Before your first run, verify that the target has kexec support and at least 1 GB of RAM when kexec is used, and check that the machine is reachable over the public internet or a local network, since the README states wifi is not supported.

Frequently asked questions

Official sources

1. License: MIT
2. nix-community/nixos-anywhere on GitHub
3. Project website
4. README
5. Releases