FAQ

1. What is emanix?

A NixOS distribution for personal computing (em·a·nix — *Em*acs + *Nix*OS). It is the common core every host shares, reasoned about with the IOSHI three-concern architecture and laid out in two tiers, home/ and modules/, split by module system.

It was called eminix until 2026-08-30, when it was renamed to sit closer to the two things it is actually built from.

2. Is it a Linux distribution I can download?

No — it is a configuration, not an ISO. It is a Nix flake you apply to a NixOS installation. Install NixOS, then apply emanix.

3. What hardware does it support?

Anything NixOS supports. It runs today on a laptop as a full graphical desktop, on a headless always-on server, and inside NixOS-WSL on a Windows machine — from one distribution with no per-shape variants, because shape is composed by the consuming flake rather than chosen from a menu here.

Hardware support is not in this repository at all; it is a module you write. What the distribution ships is the capability — emanix.hardware.gpu and the redistributable-firmware default — never a fact about your machine. That makes adding a machine a module, not a fork.

4. Can I use it without Emacs?

Technically yes, practically no. Emacs is the intelligence interface, not an editor choice — the compositor runs inside the Emacs process and the agent tooling are Emacs packages. Removing Emacs leaves you with the substrate and the architecture, which is a reasonable thing to fork but is not emanix.

5. What is EWM?

A Wayland compositor written in Rust on Smithay, loaded as a dynamic module inside Emacs. Windows, workspaces and status bar are Emacs objects, so keybindings and configuration are one language everywhere. EWM is an upstream project — codeberg.org/ezemtsov/ewm — not part of Emanix. Emanix packages it, launches it, and themes it.

6. What is IOSHI?

Three concerns:

  • i — intelligence interface — the workspace
  • os — operating system — the substrate
  • hi — hardware / internet — the machine and its network, of which the distribution ships the capability and none of the facts

They are how the distribution is reasoned about. The directories are split another way — by module system, into home/ and modules/. See Architecture.

7. How do I update?

cd ~/dotfiles
nix flake update
sudo nixos-rebuild switch --flake .#<host>

Updates move the flake's input pins. There is no apt upgrade.

8. How do I roll back?

sudo nixos-rebuild switch --rollback

Every rebuild creates a generation. The bootloader lists them too, which is the way out when a change breaks the graphical session.

Note what rollback does not restore: live-edited files symlinked out of the store, and any data a service mutated. See Build and Deploy.

9. Where are my secrets?

Age-encrypted in the repository, decrypted at activation by each host's own SSH host key. See Secrets.

10. Why does my host decrypt a secret it never uses?

Because recipient status and use are different things. A host is granted decryption by the recipient list; whether it deploys the credential is a separate flag. Setting that flag false does not remove the host from the recipient list — edit the recipients and re-encrypt if that is what you want.

11. I changed a generated config file and it reverted

That file is a build product. Change the option that generates it and rebuild. This is correct declarative behaviour and it surprises everyone once.

12. I set a theme and nothing changed

Check the spelling. emanix.theme is an enum, so an unknown name is an eval error that names the valid set — a typo fails the build rather than quietly falling back to the default. See Theming.

13. How do I add a host?

A machine file, a username, and a build: copy the template's host.nix, set the username in the flake, and let lib.mkDisk build the layout from the four disk values. See Adding a Host.

14. Why is the option namespace emanix.*?

It was named after an individual until 2026-08-14. The namespace is the distribution's public API, and naming it after a person made it both awkward to adopt and wrong in principle. See Options.

15. Can I fork it?

Yes, and the seams are documented for exactly that. The tier structure, the module layout, the theme system and the host composer generalize. The shell aliases, agent instructions, git identity and mesh enrolment do not — replace them rather than inheriting them. See Adding a Host.

16. Where can I learn more?