Use the official NixOS installer

If you already have a monitor and keyboard (or an IP KVM) attached to the target machine, you can install stock NixOS with the upstream graphical installer and then convert the machine into a sway-home host after the fact. You do not need to build a custom ISO first.

Install stock NixOS

Follow the official NixOS manual to install NixOS from the official graphical installer ISO. During the install, select No desktop – that setting is overridden by sway-home anyway.

Reboot into the freshly installed system and log in as the user you created during the install.

Convert the install into a sway-home host

The setup-host generator that the custom ISO uses can also be run straight from GitHub, on top of a stock install. With its --adopt flag it reuses the installer’s existing partitioning and /etc/nixos/hardware-configuration.nix instead of generating a disko.nix.

Run it as your normal user (not root):

nix shell --extra-experimental-features "nix-command flakes" \
  nixpkgs#babashka nixpkgs#git github:EnigmaCurry/script-wizard -c \
  bb -e '(load-string (slurp "https://raw.githubusercontent.com/EnigmaCurry/sway-home/master/bin/setup-host.bb"))' \
  -- --adopt

It prompts for the hostname, your username, time zone, and the profiles to enable; seeds any SSH keys already authorized for you into config.nix; then writes ~/nixos and runs git init plus nix flake lock. When it finishes it prints the exact nixos-rebuild switch command for your hostname – run it as-is for this first apply. The admin helper isn’t on PATH yet (it comes from the sway-home profile), so the initial bootstrap has to go through nixos-rebuild directly.

Review ~/nixos/config.nix first (add an SSH key if none was found, flip any profile toggles), then run the command the installer printed. It will look something like:

sudo nixos-rebuild switch --flake ~/nixos#YOUR_HOSTNAME

That switch is the step that replaces the stock configuration. After it completes, admin upgrade becomes available and is what you’ll use for every subsequent change.

Your data is left alone – partitions and home directories are untouched. From here your machine is a full sway-home host and the rest of this book applies unchanged: skip the Build a custom installer ISO section (that whole flow is specific to the custom ISO) and continue at Making changes going forward.

Caveats specific to skipping the custom ISO

• UEFI + systemd-boot is assumed. sway-home hard-codes boot.loader.systemd-boot.enable, which matches the graphical installer’s default on UEFI machines. On a legacy BIOS / GRUB machine the switch will fail – add a boot.loader.grub block in config.nix (with lib.mkForce to disable systemd-boot).
• Match the release. sway-home pins system.stateVersion to a specific release, so install the matching NixOS release (or override system.stateVersion in config.nix to whatever you installed).
• Your install password persists. The shared config keeps users.mutableUsers at its default (true), so the password you set during the graphical install carries over.

Full details, including how to enable sshd on the stock install for a remote convert, and how to rotate host keys on a disk cloned from an image, are in the sway-home NIXOS.md under Option B.