Components

The centre of the system, and the reason for the rest of it. A pgtk build with a curated package set and modal editing.

There is exactly one Emacs build. Which one you get depends on emanix.ewm.enable:

• true — the system-owned build, carrying the compositor's own package, put on the system PATH so emacsclient is available everywhere. Home Manager delivers configuration only, never a second Emacs.
• false — the same package set minus the compositor, installed at the home level and run as a systemd user service.

Two builds of Emacs on one machine is the failure mode this design exists to prevent.

A Wayland compositor written in Emacs Lisp. Windows, workspaces, status bar: all of it is Emacs, so keybindings and configuration are one language.

It launches from the TTY login shell, inside the logind session scope. This is not the obvious approach — there is a shipped systemd user unit — but that unit runs outside any session and cannot acquire display-master without a display manager. Launching from the login shell was the working path.

Three details in that launch are load-bearing and were each found the hard way:

• One compositor per boot session. A stale daemon holds display-master and starves every new launch, so the launcher kills a prior instance first — and matches on the full command line, because the Nix wrapper truncates the process name.
• A flap guard. If the compositor crashes in a loop, a marker file drops you to a normal shell instead of an unusable login cycle. Remove it to re-arm.
• Keyboard options are set in the environment, not in the compositor's own config, because the keymap is built at compositor start — configuration applied afterwards is simply too late.

A GPU-accelerated terminal, gated on emanix.ghostty.enable; zsh with completion and a themed prompt; and an optional multiplexer that SSH logins land in, so remote sessions survive disconnection.

Emanix ships neither an agent nor a local inference server. An AI harness is not a decision a distribution should make for you, and a model runner is a substantial dependency to impose on a machine that may not want it.

What Emanix does ship is the wiring: an emanix-pi.el launcher bound to C-c p, and a secret store your flake can point at a credential. Supply an agent and the binding works; supply none and it does nothing. See Secrets for why credential use and credential access are separate questions.

Search and file tooling, git and its helpers, a formatter and linters for Nix itself, Python tooling, media tooling, screenshot and screen-recording utilities for Wayland, a password manager, and fonts.

The list is one place. Feature flags decide which of it materializes: a host with emanix.gui = false does not receive the GUI applications, because the modules that provide them are gated on that flag. Nothing consults the role.

Shell, primary user, timezone, locale, console keymap, and the Nix settings that make the rest sane:

• Flakes and the modern CLI enabled
• Store auto-optimisation
• Daily garbage collection, deleting generations older than two weeks
• A mid-build emergency valve: when free space drops below a floor, Nix collects garbage during the build until a ceiling is available again

That last pair matters more than it looks. A weekly timer is not enough on a host that builds often — a churning machine can accumulate many gigabytes of dead paths within a day or two of a successful collection. And on a virtualised host whose disk image never shrinks below its high-water mark, garbage that lives a week costs real disk on the host side even after it is finally collected.

Audio, Bluetooth, printing, containers, touchpad tuning, the bootloader.

Headless target, containers, networking, the bootloader — and the secret store, imported individually rather than by pulling in the intelligence directory, which is a Home Manager aggregate and does not evaluate at system level.

Packages the one-time post-install command. It is built with a wrapper that shellchecks the script at build time, so a broken helper fails the build rather than the install.