ephemeral
System state starts clean.
/ is recreated from an empty snapshot on every boot. 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 installs an opinionated NixOS desktop on an encrypted btrfs disk and wipes the root filesystem on every boot. Your home folder and a short list of declared paths live on /persist; everything else comes back from the config.
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
The ideas behind it.
declarative
The machine is a flake.
A short flake.nix pins a tested release of the config, and settings.json holds your answers. The lock file pins everything else, so the same release builds the same system. Each feature is one module file.
hardened
Hardened, within reason.
Full-disk encryption, a closed firewall, OpenSnitch asking before programs connect out (on the full profile), kernel hardening and sandboxed services, without turning the desktop into a chore. The security page lists what each one doesn't cover, too.
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" ];
};
}To keep something else, add a module like this one and run ephemeral-update. ephemeral-doctor kept lists everything a machine keeps.
04Security
Locked down by default, with known gaps.
- 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
- The IOMMU only guards against DMA once the kernel is running
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.2.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
New here? Start with the first hour.
- 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.2.0 | 2026-11-13 | Patch release each Monday with the newest nixpkgs, after the boot tests pass |
| ephemeral-nixos | v3.7.7 | 2026-11-13 | Each Tuesday it moves to the newest config release once the install test passes; installs config v4.2.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.