USB Boot (potato)

potato is a stopgap host: a small graphical NixOS system installed onto removable storage, for whichever machine currently has no disk of its own. It is deliberately hardware-agnostic — the only fact it pins is the target drive.

It exists as a host in its own right rather than a variant of desktop or laptop because its disko declares the flash drive as the only disk, and its feature and package sets are cut down to what that drive can hold. Keeping it separate leaves the real host configurations untouched while it is in use.

This page covers what makes potato different. Installing it, unlocking it over SSH and converging it are the same procedure as every other host — reference the initial setup guide, which carries a Potato tab for each step.

Design

The single host-specific fact is the target disk, in hosts/potato/nixos/disko.nix. Everything else is detected or generalized:

To deploy onto a different machine, update the device in disko.nix to that drive’s /dev/disk/by-id/ path and regenerate facter.json. Nothing else changes.

Initrd Network Drivers

nixos-facter sets boot.initrd.availableKernelModules for disk and keyboard, but its networking module only handles DHCP interfaces — it supplies no initrd NIC driver. That is why bootloader.nix keeps networkCardModules by hand.

potato lists the union of every driver its possible targets need rather than one hardware fact. availableKernelModules is include-if-present, so naming drivers the kernel does not have costs nothing. Add to that list if a target’s NIC is not covered; without it, remote LUKS unlock will not come up and the passphrase must be entered at the console.

Feature Set

values/potato.nix is values/bootstrap.nix plus the smallest set that yields a usable graphical session.

A full workstation closure does not fit. One generation already exceeds 75 GB and a nixos-rebuild switch needs room for two, against roughly 110 G of usable space.

Excluded on purpose:

Packages stand apart from values/packages/workstation.nix for the same reason; reference values/packages/potato.nix.

Disk Layout

ESP of 1 G, swap of 6 G, and the remainder as a LUKS container holding the @root, @persist and @nix btrfs subvolumes.

Two details are load-bearing.

Only the target disk is declared. disko destroys every device it is told about, so naming only the flash drive is what keeps --phases disko away from the data disks already present in the host machine. Mount those by hand when needed.

The root LUKS container is named crypted-nvme, named for the convention rather than the hardware. Both the initrd blanking unit in bootloader.nix and scripts/btrfs-impermanence.nu reference that mapper name literally, so a host using the shared impermanence machinery must use it.

The device is addressed by-id, never /dev/sdX: removable media takes whichever letter is free at boot, frequently the one an installed disk had.

Persistent Root

potato is the only host whose @root subvolume survives a reboot. A disposable machine is not worth the discipline of declaring every path worth keeping, and state a module never thought to persist would otherwise be discarded on every boot.

The flake passes ephemeralRoot = false for this host, which leaves the initrd btrfs-blank-root unit in modules/features/bootloader.nix defined but never pulled into initrd.target. Nothing else changes: the /persist bind mounts declared across the feature modules stay exactly as they are, so state already living there keeps doing so, and the subvolume remains load-bearing for the sops age key, the initrd SSH host key and the out-of-store symlink targets used by neovim.nix and app-state.nix.

Network

potato answers to 10.100.0.4 on the WireGuard mesh. The address is hostname-keyed in values/network-details.nix, so modules/features/wireguard.nix resolves it with no host-specific branching. The server must be rebuilt after the entry changes, so it learns the peer.