Glossary

• Emanix — the distribution: Em=acs + =Nix=OS. A NixOS distribution for personal computing, organized around the IOSHI architecture. Not an ISO — a flake applied to a NixOS installation. Written *Emanix* in prose and =emanix in code, paths and options. See the index.
• flake — the single source of truth. The formal specification of what a machine should be, applied to a NixOS installation. If it is not in the flake, it does not exist.
• IOSHI — the three-concern architecture: i=ntelligence → =o=s → =hi (hardware / internet). A way of deciding where something belongs, layered by rate of change. The distribution owns the first two. See Architecture.
• layer — one of the three IOSHI concerns. A boundary; a change touching two layers at once is a signal the boundary is wrong.
• core — emanix.nix. What is true of every Emanix box: base system, firstboot convention, the intelligence layer. Emanix is never a hostname.
• consumer — the flake that imports Emanix and calls lib.mkHost. It supplies everything personal: hosts, hardware, disks, network, secrets, keys and the user's own Home Manager config. The distribution supplies everything generic. That line is the whole design.
• host — one machine, assembled by lib/mkHost from the core plus whatever the consumer passes in. Host names are arbitrary; commands are written .#<host> throughout these docs.
• mkHost — the host composer. Takes hostName, role, username, an optional hardware module, extraModules and homeModules; returns a nixosSystem. See Adding a Host.
• role — a label, not a mechanism. One of workstation, server or wsl, recorded on emanix.role and exported as EMANIX_ROLE. It imports nothing and gates nothing in the distribution; consumers may branch on it. Role profiles existed until 2026-08-30 and were deleted — see Architecture.

• intelligence interface — the workspace: Emacs, the EWM compositor, the terminal, the shell, theming. The layer the user actually works in, and the one that changes most often. Mostly Home Manager, though not exclusively.
• EWM — a Wayland compositor written in Emacs Lisp. Windows, workspaces and status bar are all Emacs, so keybindings and configuration are one language. Launches from the TTY login shell, one compositor per boot session, with a flap guard. See Components and Keybindings.
• pgtk — the Emacs build variant used throughout: a pure GTK build with a curated package set and modal editing. Exactly one Emacs build exists; which one you get depends on emanix.ewm.enable.
• Meow — the modal editing scheme: select first, then act. See Keybindings.
• live elisp — the one deliberate seam. Emacs Lisp symlinked out of the Nix store so edits take effect on restart with no rebuild, at the cost of not being content-hashed into the generation. Governed by emanix.src.liveElisp.

• substrate — the operating-system layer: base and firstboot, and nothing else. Anything a person interacts with belongs one layer up; anything specific to a machine belongs to the consumer. See Architecture.
• base — the module shared by every host: user and shell, timezone, locale, console keymap, Nix experimental features, store optimisation, garbage collection. Locale, timezone and keymap are defaults, meant to be overridden.
• firstboot — the one-shot post-install command, emanix-firstboot. Emanix owns the convention and shellchecks the script at build time, so a broken script fails the build rather than the install; the content comes from the consumer via emanix.firstboot.text. See Installation.
• stateVersion — a historical fact: the release a machine was first installed under. Never shared between hosts, never bumped on an existing one. It is not a version to keep current.

This layer is not in the distribution. The terms still matter, because your flake supplies them.

• hardware module — per-machine facts only: initrd modules, firmware, power management. A driver quirk that leaks above this layer is a bug.
• initrd — the initial ramdisk. A GPU module the compositor depends on must load here; bringing it up after userspace loses the display-master race.
• display-master — the race for control of the display between a compositor launched from a TTY and anything else that claims it. Load-bearing in one line of the hardware module and nowhere else.
• disk layout — declarative, described with disko and generated from the description. Never hand-written alongside it; a second definition fails the build on purpose. See Adding a Host.
• mesh (mesh VPN) — a coordination server so hosts reach each other without a third party. Emanix ships none: choosing one is a networking decision, and networking is the consumer's. NixOS makes it a few lines.

• secret — a value age-encrypted in the repository (a .age file) and decrypted at activation by each host's own SSH host key, into a root-owned runtime directory with an explicit owner and mode. Modules point at the decrypted path; they never carry the value. See Secrets.
• recipient — a host whose key may decrypt a given secret. Recipient status is not the same as use: a host can decrypt a secret it never deploys.
• agenix — the tool used to edit a .age secret. Emanix wires the module through mkHost; which secrets exist, and who may read them, is declared by the consumer. Re-encrypted files are safe to commit; that is the point.

• generation — the output of every rebuild, and a rollback target. The bootloader lists them, which is the escape hatch when a change breaks the graphical session. Rollback restores the system closure, not live-edited files and not data. See Build and Update.
• derivation — Nix's build artifact identity. Comparing derivation paths (drvPath) proves whether a refactor changed anything, with no build and no root. Identical paths = provably inert.
• closure diff — the stronger version of the same check, for changes that are not expected to be byte-identical: nix store diff-closures names every package that entered or left. A pure rename shows only the renamed entries.
• input pins — the flake's locked inputs. Updates move the pins (nix flake update), never an apt upgrade. A bad update's blast radius is one rollback.
• build product — a generated config file. Editing it by hand does nothing durable; the next activation discards it. Change the option that generates it and rebuild. See Theming.
• high-water mark — what a virtual disk image is: it grows and does not shrink when files are deleted inside the guest. Garbage collection frees space to the guest, not the host.

The distribution's public API. Mostly Home Manager options, set inside home-manager.users.<user>; emanix.username and emanix.firstboot.* are NixOS-level. Nothing is set by a role, because roles set nothing. See Options Reference for the full list.

• emanix.username — which user the distribution configures. Set by mkHost.
• emanix.role — the label described above. Set by mkHost. Selects nothing.
• emanix.gui — this machine has a graphical session. Gates cursor theme, Wayland tools, GUI applications, screen locker, terminal config.
• emanix.ewm.enable — this machine's Emacs is the system-owned EWM build. The single switch between "Emacs is my desktop" and "Emacs is an editor with a daemon".
• emanix.theme — the active palette. An enum, so a typo is an eval error naming the valid set rather than a runtime surprise.
• emanix.src.path / emanix.src.dotfilesPath — the Emanix checkout and the consumer's checkout. Two different things; conflating them is the classic mistake.
• emanix.src.liveElisp — the live-elisp seam described above.
• emanix.ghostty.enable — the GPU-accelerated terminal. Defaults to emanix.gui, but separable so a headless-but-terminal host can opt in.
• emanix.zellij.enable — the terminal multiplexer; SSH logins land in a persistent session.
• emanix.firstboot.text — the first-boot script. Yours to write.

• Home Manager — the user-level configuration system the intelligence layer is built on. An aggregate import fails to evaluate at system level; where a system-level module is needed, it is imported individually.
• WSL — Emanix runs inside Windows with no hardware layer: the WSL module supplies boot and mounts, WSLg supplies the display. The system must not set its own hostname at activation, so the composer sets it as a default and a WSL host forces it empty.