Boot the installer and run setup

With your custom ISO written to a USB stick, you are ready to install NixOS onto the target machine.

Boot the machine

Plug the USB stick into the target machine and boot from it. The first time, you will likely need a monitor and keyboard attached to tell the machine to boot from USB: many computers let you pick a one-time boot device from a menu (often F12, but the key varies by manufacturer), or you can enter the UEFI/BIOS setup and change the boot order permanently. Once the machine boots the installer, the rest of the install is fully headless – you can unplug the monitor and keyboard and continue over SSH.

Because the ISO is headless, the installer brings up the network on its own, joining the WiFi network you pre-seeded (if any).

Once the network is up, the webhook you configured (if any) receives a JSON message with the machine’s hostname, its local IP address, the login user, and a ready-to-use ssh command. This tells you where the machine landed on your network.

Connect over SSH

SSH into the machine as root, using one of the SSH keys you baked into the ISO (password login is disabled):

[bash]: Run this on your workstation:

ssh root@<ip>

You can also log in at the physical console (or over the serial console, if you enabled one), but SSH is the universal path.

Run setup

Everything from here on is done with a single command. Run setup with no arguments to open the installer’s main menu:

sway-home NixOS setup main menu
> Configure Disk
  Configure Host
  Install
  Done

The install is three phases, run in order. Pick each one to run it, then return to the menu for the next, until you choose Done (or press ESC). The menu lets you re-run a single phase on its own if it fails.

The three phases are:

Configure Disk – partition, format, and mount the target disk.
Configure Host – generate this machine’s own NixOS flake repository.
Install – run nixos-install and set the passwords.

If you would rather skip the menu and run all three back to back, setup nixos chains them in order, each with its own prompts, stopping at the first failure.

The remaining pages in this chapter walk through each phase in order.