/install

Install Ephemeral Nix.

The installer asks one question per screen and shows a review before anything is written. The current release is v3.7.6.

01Before you install

Requirements and preparation.

Hardware

An x86_64 PC that boots in UEFI mode. The installer stops on legacy BIOS boots.
Secure Boot off in the firmware settings.
One whole disk for the system.
Enough RAM to build the system. The install test uses 6 GB; less hasn't been tried.
Wi-Fi or a cable. The system is downloaded during the install.
For a VM: UEFI with Secure Boot off and a VirtIO disk. 64 GB of disk and 8 GB of RAM is plenty.

Hardware lists what's been tested and what's detected.

Checklist

Back up everything on the disk you want to keep.
Unplug other disks you don't mean to install on, especially one with an older Ephemeral Nix install: the new system boots by partition names that one has too, so the installer refuses while it's attached.
Pick a passphrase you can type at the boot screen. It uses the keyboard layout you choose in the installer.
Know the limits: one user per machine, suspend but no hibernation, passphrase unlock only (no TPM).

02From the ISO

The easiest way.

Download the .iso and SHA256SUMS from the v3.7.6 release, check them, and write the ISO to a USB stick. Replace /dev/sdX with the stick: dd overwrites whatever it's given.

Boot it in UEFI mode. The installer starts on its own. esc goes back, and a review screen at the end lets you change any answer before anything is written. With no network yet, it starts on Connect to Wi-Fi; the network you join is copied to the new system.

Run ephemeral-install to start it again. If you leave it while it's installing, the install carries on, and running it again picks it back up.

shell

sha256sum -c SHA256SUMS
gh attestation verify ephemeral-nix-*.iso -R the-wittch/ephemeral-nixos
gh release verify-asset ephemeral-nix-*.iso -R the-wittch/ephemeral-nixos
sudo dd if=ephemeral-nix-*.iso of=/dev/sdX bs=4M status=progress oflag=sync

03The questions

What the installer asks.

diskThe whole disk to install on. A USB drive shows a warning; the stick you booted from is refused.
desktopPlasma, GNOME, niri or Umbriel. niri and Umbriel come with the Noctalia shell.
regionKeyboard layout, language and timezone, each searchable.
machineHostname, user name and swap size.
secretsThe LUKS passphrase, after switching the console to your layout, and the login password.
profileThe full system, or a small install: a plain desktop you finish later with ephemeral-setup.
optionsFor the full system: extras, OpenSnitch, the Proton Pass SSH agent and Control D, then the same apps as ephemeral-apps.
hardwareNVIDIA drivers if it finds a card, fingerprint login if it finds a reader. Laptop extras turn on when there's a battery.
confirmIt shows what the disk becomes, then you type the disk's name. Only then is it erased.

An NVIDIA driver is compiled during the install, which adds a few minutes. When it's done, remove the stick and reboot.

04From the NixOS ISO

With a verified clone.

Boot the NixOS graphical ISO in UEFI mode and connect to the network. Take the tag and commit from the latest release, or from RELEASE on that tag, and check the clone against them:

from release v3.7.6 (recommended)

TAG=v3.7.6
REV=23ea4e7a35353d53b1d42fe93e6cdac557b707c4
git clone --branch "$TAG" --depth 1 https://github.com/the-wittch/ephemeral-nixos.git ~/nix
cd ~/nix
[[ $(git rev-parse HEAD) == "$REV" ]] || echo "hash mismatch, stop here"
sudo ./scripts/tui.sh

Or let the bootstrap script clone and check it:

shell

curl -fsSL https://raw.githubusercontent.com/the-wittch/ephemeral-nixos/v3.7.6/scripts/bootstrap-tui.sh -o /tmp/bootstrap-tui.sh
sudo env TAG=v3.7.6 EXPECTED_REV=23ea4e7a35353d53b1d42fe93e6cdac557b707c4 bash /tmp/bootstrap-tui.sh

From main, without a pinned release

shell

git clone https://github.com/the-wittch/ephemeral-nixos.git ~/nix
cd ~/nix
sudo ./scripts/tui.sh

Installs without menus are on Unattended installs, and the same steps by hand on Manual install. Use sudo env VAR=...; plain sudo VAR=... usually drops the variables.

Release tags are signed, so GitHub shows them as Verified. Weekly releases are tagged by CI and aren't signed; since v3.7.3 GitHub signs a record of every release's tag and files instead, which gh release verify "$TAG" -R the-wittch/ephemeral-nixos checks. Checking the commit hash as above works for every release.

05After the install

The first boot.

The config is at /persist/etc/nixos. After a small install, run ephemeral-setup to get the full system. Then follow The first hour: check the machine, pick apps, back up the LUKS header, and put the config in git.

To see the wipe working, make a file in / and one in your home folder, and reboot. The first is gone, the second is still there.

shell

ephemeral-update     # rebuild after a change, and move to new releases
ephemeral-doctor     # check the machine; says how to fix what isn't right
ephemeral-apps       # pick extra apps
ephemeral-help       # every command

the wipe test

sudo touch /ephemeral-test
touch ~/still-here
systemctl reboot

06Troubleshooting

If something goes wrong.

Situation	Where to look
The installer stops with an error	It says how far it got; nothing is erased before the confirm step. Install problems explains each message. "Try again" starts over safely.
Black screen at the LUKS prompt	Install problems: `plymouth.use-simpledrm`, or load your GPU driver early.
A rebuild broke the system	`ephemeral-update --previous`, or pick the previous entry in the boot menu. When something breaks.
Back to the system as installed	`ephemeral-update --as-installed` rebuilds from the read-only copy in `/persist/etc/nixos-install`. Your files stay.
The disk won't unlock with the right passphrase	Restore the LUKS header backup from the NixOS ISO. When something breaks.
An app can't connect	Check OpenSnitch's rules first. OpenSnitch.

Report a failed install with the end of /tmp/ephemeral-install.log as an install problem. Once the machine boots, problems go to the config's tracker with the output of ephemeral-report.