Philosophy
Table of Contents
emanix exists because personal computing should be legible.
Most systems are opaque by accumulation rather than by design. You install
them, they work, and the reasons are scattered across dotfiles, service units,
half-remembered apt invocations and a manual step someone performed once. When
something breaks you search for an answer written about a different machine.
The failure mode is not that this is hard. It is that the machine's current state is not written down anywhere, so nobody — including its owner — can say what it actually is.
1. Principles
1.1. One source of truth
The flake is the single source of truth. No hidden state, no manual steps "everyone knows", no tribal knowledge. If it is not in the configuration, it does not exist.
This is a claim you can falsify, which is what makes it useful. Every undocumented file on a running machine is a small refutation of it.
1.2. Reproducible
Any emanix machine can be rebuilt from the configuration alone. The same input produces the same output — not approximately, but by construction: the same inputs hash to the same derivation.
That property is directly testable, and it is worth testing. Comparing derivation paths before and after a refactor answers "did this change anything?" exactly, without building anything or touching a machine.
1.3. Composable
Emanix is a core, not a monolith. A host is the core plus whatever the flake consuming it composes on top. The same package list produces a different derivation per host, because the modules gate on feature flags rather than shipping everything everywhere — GUI applications simply do not exist in a headless build.
Composability is why there are no roles. A role profile is a guess about which machines want which behaviour, made by someone who has never seen the machine. Deleting them did not remove a capability; it moved a decision to the only place that can make it correctly.
1.4. Declarative
Declare what you want; let the system work out how. No imperative package management, no state mutation, no side effects. System state is a pure function of the configuration.
1.5. Reversible
Every rebuild produces a generation, and every generation is a rollback target. This is what makes the rest safe: a declarative system you cannot back out of is just a slower imperative one.
1.6. Portable
The same workspace on a laptop, a headless server and a Windows machine under WSL. The interface travels; only the substrate changes.
2. Why NixOS
NixOS is the only mainstream Linux distribution that makes these principles practical rather than aspirational. Functional package management, declarative configuration and atomic rollback are what let you know exactly what is on a machine, reproduce it, and undo a mistake in one command.
The honest counterweight: NixOS moves the difficulty rather than removing it. Instead of debugging a machine's accumulated state you debug a configuration language, and the error messages are worse. The trade is worth it because configuration errors are reproducible and accumulated state is not.
3. Why Emacs
Emacs is the intelligence interface, not the editor. It is a programmable environment where reading, writing, file management, version control and agent interaction share one set of keybindings and one configuration language.
The practical argument is narrower than the philosophical one: the cost of learning a general environment is paid once, and the cost of learning ten special-purpose tools is paid ten times and then again whenever one is replaced.
4. Why EWM
EWM is a Wayland compositor written in Emacs Lisp. It removes the boundary between "editor" and "desktop" — the window manager is the same program, in the same language, with the same configuration.
This is the most opinionated choice in the distribution and the least generalizable. It is also the one that makes the rest cohere: once the compositor is Emacs, there is no second configuration language and no second place for state to hide.
5. What is not claimed
emanix is one person's machine, written public-shaped. It is not a product, there is no support, and the parts that encode a particular person's taste are marked as such rather than pretended away.
The architecture generalizes. The preferences do not, and should not.