ephemeral
System state starts clean.
Before / is mounted, the initrd deletes the root subvolume and makes a new one from an empty, read-only snapshot. Whatever a program left outside the kept paths is gone by the next login.
NixOS · LUKS2 · btrfs · impermanence
A clean slate.
Every boot.
Ephemeral Nix is an opinionated, declarative NixOS desktop. Its root filesystem is recreated empty at every boot; your home folder and the paths you declare are kept, on an encrypted disk, with careful security defaults.
x86_64 · UEFI · erases the whole disk · read first
nixuser@nixosthe wipe test
sudo touch /ephemeral-test # outside what’s keptecho hello > ~/notes.txt # in /home, keptsystemctl rebootreboot · / is recreated from root-blankls /ephemeral-testls: cannot access '/ephemeral-test': No such file or directorycat ~/notes.txthello/ is gone after a reboot; one in your home folder is still there. From the installer's README.
01Principles
Three ideas, held to strictly.
declarative
The machine is a flake.
A short flake.nix pins a tested release of the config. Your answers live in settings.json. Every feature is one module file, so the same release builds the same system.
hardened
Careful defaults, written down.
Full-disk encryption, a closed firewall, outbound connections that need your approval, kernel hardening and sandboxed services. Each one is documented together with what it doesn't cover.
02How it works
What happens between the passphrase and the login screen.
- unlock
systemd-boot loads the kernel from
/boot. You type the passphrase and the LUKS2 volume opens. - reset
The
rollbackunit deletes therootsubvolume and snapshotsroot-blankin its place. - mount
/nix,/persistand/var/logare mounted, and kept paths are bound from/persistinto place. - check
root-reset-checkconfirms the reset happened on this boot. If it didn't,ephemeral-doctorsays so and how to fix it.
03Persistence
An ephemeral root, not ephemeral data.
Your files are kept. What's wiped is everything else on /: the state programs scatter across /etc and /var that nobody asked to keep.
Gone at every boot
- files written to
/outside the kept list - an edit made by hand in
/etc - a database in
/var/libnobody declared /tmp, which is a tmpfs
Kept on /persist
/home, all of it- Wi-Fi connections, Bluetooth pairings
- the machine id, SSH host key, login password hash
- what each enabled feature declares
modules/keep.nix
{
flake.modules.nixos.pc.environment.persistence."/persist" = {
directories = [ "/var/lib/postgresql" ];
files = [ "/etc/machine-info" ];
};
}Keeping more is a module like this one, followed by ephemeral-update. ephemeral-doctor kept lists every kept path on a machine.
04Security
Locked down where it can be. Honest where it isn't.
- LUKS2 with argon2id over the whole system, swap included
- Firewall on, SSH off, no port open without a setting
- OpenSnitch denies outbound connections you haven't allowed (full profile)
- Kernel hardening, IOMMU on, unprivileged BPF off
- Root has no password; sudo and the Nix daemon are for
wheelonly - The config's own root services run in a systemd sandbox
- No Secure Boot;
/bootis not encrypted - Passphrase only, no TPM unlock
- Nothing protects the firmware and boot loader before the kernel runs
05Configuration
Two repositories, one pinned release.
ephemeral-nixos is the installer and nothing else. ephemeral-nixos-config holds every module a machine gets, organized with the dendritic pattern: each file is one feature, loaded automatically, adding to a few shared modules.
Your machine's flake in /persist/etc/nixos is four lines. It pins a release; nothing builds from a branch.
/persist/etc/nixos/flake.nix
{
inputs.ephemeral.url = "github:the-wittch/ephemeral-nixos-config/v4.1.0";
outputs = inputs: inputs.ephemeral.lib.mkFlake { inherit inputs; root = ./.; };
}06Installation
One question per screen, and a review before anything is written.
- 01Download the ISO and check it against
SHA256SUMSand its attestation. - 02Turn off Secure Boot, boot the stick in UEFI mode.
- 03Answer the screens: disk, desktop, keyboard, user, passphrase, profile, apps.
- 04Type the disk's name to confirm. The installer erases it and installs.
07Documentation
Plain pages that each answer one question.
- The first hourWhat to do right after installing.
- Rebuilding, updating and the helper commandsephemeral-update, ephemeral-doctor and the rest, and how releases reach a machine.
- Try it in a VMBoot the config in a throwaway QEMU window, without installing anything.
- settings.jsonEvery setting, what it does, and how unfree packages are allowed.
- CustomizingYour own modules, the shared modules you can add to, and how the config is organized.
- Optional featuresControl D, SMB, NVIDIA, Tailscale, Proton Pass, the app picker, VMs and the rest.
- Dotfiles and appearanceThe Home Manager dotfiles, the Catppuccin theme through Stylix, Plasma, the wallpaper.
- When something breaksRolling back, recovering a broken boot or a damaged LUKS header, and reporting a bug.
- Backups and snapshotsWhat to copy off the machine, hourly snapshots, the LUKS header, and restoring after a reinstall.
- Install problemsErrors the installer can stop with, what they mean, and where to report a failed install.
- HardwareWhat's required, what's been tested, and what the installer detects.
- Unattended installsEvery installer question answered ahead of time with environment variables.
- Manual installThe installer's steps by hand, without the scripts.
08Status
Maintained by one person, released every week.
| Repository | Latest | Released | Cadence |
|---|---|---|---|
| ephemeral-nixos-config | v4.1.0 | 2026-11-13 | Patch release each Monday with the newest nixpkgs, after the boot tests pass |
| ephemeral-nixos | v3.7.6 | 2026-11-13 | Each Tuesday it moves to the newest config release once the install test passes; installs config v4.0.0 |
Tracks nixos-unstable, and moves to the stable 26.11 channel once it's released. Releases are immutable. See the changelog and the roadmap.