Rebuilding, updating and the helper commands

Rebuild and update

shell

ephemeral-update

It rebuilds from /persist/etc/nixos and switches to the result, with readable progress and a list of what changed at the end. The same command takes you back when something goes wrong:

command	what it does
`ephemeral-update --check`	build a change without switching to it, to see whether it works
`ephemeral-update --previous`	go back to the system before the last rebuild
`ephemeral-update --list`	the systems you can go back to, with their dates and config releases
`ephemeral-update --as-installed`	the system exactly as it was installed; your files stay

ephemeral-doctor checks the machine: that / was wiped, what failed, free space, snapshots, whether a newer release is out, and each problem with the command that fixes it.

How releases reach a machine

flake.nix in /persist/etc/nixos pins a release of the config, for example:

nix

{
  inputs.ephemeral.url = "github:the-wittch/ephemeral-nixos-config/v4.1.0";
  outputs = inputs: inputs.ephemeral.lib.mkFlake { inherit inputs; root = ./.; };
}

ephemeral-update checks for a newer release before it rebuilds. If there is one, it links the changelog and asks whether to move to it, then changes the tag and updates the lock for you. After an install, /persist/etc/nixos belongs to root; ephemeral-update and ephemeral-setup both offer to make it yours, so it can be edited and kept in git.

To do it by hand instead, change the tag, then:

shell

nix flake update ephemeral --flake /persist/etc/nixos
ephemeral-update

While the folder still belongs to root, the first command needs sudo in front.

Read the changelog before a new major version; it lists what you have to change. Settings that were removed still load with a warning that says what to do.

A machine gets new packages, security fixes included, only with a new release. A patch release comes out every Monday with the newest nixpkgs, once it passes the boot tests. The other inputs, such as Home Manager and Stylix, are updated once a month after the maintainer has read what changed upstream. The config tracks nixos-unstable and moves to the stable 26.11 channel once that’s released. For fixes sooner, give your machine its own nixpkgs, which replaces the config’s:

nix

inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

and update it with nix flake update nixpkgs --flake /persist/etc/nixos. That combination isn’t tested, so try it with nix run path:.#vm first.

Commands

ephemeral-help lists these, so there’s no need to remember them:

command	what
`ephemeral-update`	rebuild after a change and get new releases; `--check`, `--previous`, `--list` and `--as-installed` as above
`ephemeral-doctor`	check the machine and say how to fix what isn’t right; `kept` and `lost` show what survives a reboot
`ephemeral-setup`	switch between the full system and the small install, and turn the main options on or off
`ephemeral-passwd`	change your login password
`ephemeral-backup <folder>`	save the settings and secrets a reinstall needs, encrypted
`ephemeral-report`	system details to paste into a bug report
`controld-setup`	set or turn off the Control D resolver id
`smb-setup`	add or remove SMB shares
`ephemeral-apps`	pick extra apps by category, then rebuild
`luks-header-backup <file>`	copy the LUKS header to a USB stick
`settings-from-pass`	pull settings from Proton Pass
`ssh-pubs-from-pass`	write SSH public keys from Proton Pass to `~/.ssh`
`update-pass-cli`	bump or check the pinned pass-cli (run in a checkout of the config repo)

Most of them ask what to do; --help on one shows its options. The small install has ephemeral-update, ephemeral-doctor, ephemeral-setup, ephemeral-passwd, ephemeral-backup, ephemeral-report and luks-header-backup; ephemeral-help lists the ones a machine has.