Repository files navigation

Install NixOS everywhere via ssh

Documentation Index

Setting up a new machine is time-consuming, and becomes complicated when itneeds to be done remotely. If you're installing NixOS, thenixos-anywheretool allows you to pre-configure the whole process including:

• Disk partitioning and formatting
• Configuring and installing NixOS
• Installing additional files and software

You can then initiate an unattended installation with a single CLI command.Sincenixos-anywhere can access the new machine using SSH, it's ideal forremote installations.

Once you have initiated the command, there is no need to 'babysit' theinstallation. It all happens automatically.

You can use the stored configuration to repeat the same installation if you needto.

If you have machines on a mix of platforms, you'll need a common installationsolution that works anywhere.nixos-anywhere is ideal in this situation.

nixos-anywhere can be used equally well for cloud servers, bare metalservers such as Hetzner, and local servers accessible via a LAN. You can createstandard configurations, and use the same configuration to create identicalservers anywhere.

You first create Nix configurations to specify partitioning, formatting andNixOS configurations. Further options can be controlled by a flake and byrun-time switches.

Once the configuration has been created, a single command will:

• Connect to the remote server via SSH
• Detect whether a NixOS installer is present; if not, it will use the Linuxkexec tool to boot into a Nixos installer.
• Use thedisko tool to partition andformat the hard drive
• Install NixOS
• Optionally install any Nix packages and other software required.
• Optionally copy additional files to the new machine

It's also possible to usenixos-anywhere to simplify the installation on amachine that has no current operating system, first booting from a NixOSinstaller image. This feature is described in thehow-to guide.It's useful because you can pre-configure your required software andpreferences, and build the new machine with a single command.

Important Note: Never use a production server as the target. It will becompletely overwritten and all data lost. This tool should only be used forcommissioning a new computer or repurposing an old machine once all importantdata has been migrated.

• Source Machine:

  • Can be any machine with Nix installed, e.g. a NixOS machine.

• Target Machine:

  • Unless you're using the option to boot from a NixOS installer image, orproviding your ownkexec image, it must be running x86-64 Linux with kexecsupport. Mostx86_64 Linux systems do have kexec support. By providingyour ownimageyou can also perform kexec for other architectures eg aarch64
  • The machine must be reachable over the public internet or local network.Nixos-anywhere does not support wifi networks. If a VPN is needed, define acustom installer via the --kexec flag which connects to your VPN.
  • Whenkexec is used the target must have at least 1 GB of RAM, excludingswap.

TheQuickstart Guide gives more information on how torunnixos-anywhere in its simplest form. For more specific instructions tosuit individual requirements, see theHow To Guide.

nixos-anywhere makes use of thedisko tool to handle the partitioningand formatting of the disks.

For questions, come join us in thenixos-anywhere matrix room.

This software is provided free under theMIT License.

This project is supported byNumtide.

We are a team of independent freelancers that love open source.  We help ourcustomers make their project lifecycles more efficient by:

• Providing and supporting useful tools such as this one
• Building and deploying infrastructure, and offering dedicated DevOps support
• Building their in-house Nix skills, and integrating Nix with their workflows
• Developing additional features and tools
• Carrying out custom research and development.

Contact us if you have a project in mind, or ifyou need help with any of our supported tools, including this one. We'd love tohear from you.