Nix Config Desktop

Changing the desktop

The desktop is a Niri + Noctalia Wayland session, shared by two hosts: ai-niri (hostName ai, x86_64) and shoukei-niri (hostName shoukei, Apple Silicon). Shared config lives in home/linux/gui/**; each host adds hosts/<dir>/niri-hardware.kdl and its own home/hosts/linux/<dir>.nix. Run hostname to know which one you are on.

Most of the config is deployed as out-of-store symlinks, so an edit takes effect live, rolls back with git, and needs no rebuild. Only the store layer needs one.

Core rules

1. Edit the config layer, not the store. Niri KDL and the Noctalia baseline are symlinked out of store; editing them applies immediately. A rebuild is wasted time and hides the change behind a generation. Scale the caution to the risk: a bar, OSD, notification, or wallpaper tweak is safe to try on the running session and undo with git, but a compositor, keybinding, input, output, idle, or portal change can take the session the user is looking at down with it. Treat that second kind as impactful, and do not experiment on the live desktop with it.
2. Validate before trusting a reload. A config that fails to parse does not crash the session: Niri keeps the last working config and shows a "Failed to parse the config file" notification. The edit silently does not apply, which is easy to misread as "my edit did nothing".
3. Look at it. Anything that renders (bar, OSD, notifications, wallpaper, corners) is not done until a screenshot shows it correct. A setting that parses is not a setting that looks right.
4. Screenshots are the user's screen. Capture as little as proves the change, keep the file out of the user's folders, and delete it afterwards (step 3).
5. just niri is the user's to run. It activates the machine you are on through nixos-rebuild --sudo and blocks on a password prompt.

1. Pick the layer

Live (out-of-store, applies on save):

• Niri compositor (binds, layout, window rules): home/linux/gui/niri/conf/*.kdl
• Niri per-host outputs: hosts/<dir>/niri-hardware.kdl
• Noctalia shared baseline: home/linux/gui/base/noctalia/config/config.toml
• Mozc dictionary: home/linux/gui/base/fcitx5/mozc-config1.db
• Noctalia value saved by the Settings UI: ~/.local/state/noctalia/settings.toml (not in the repo; wins over the rest)

Store (needs the user to run just niri):

• Noctalia per-host override: home/hosts/linux/<dir>/noctalia.toml (host-<host>.toml)
• fcitx5 profile and addons: home/linux/gui/base/fcitx5/
• vinput (voice input): home/linux/gui/base/vinput/ (tag-pinned: the fcitx5-vinput row in WORKAROUNDS.md §Pins)
• Interface a net-speed widget reads: home/hosts/linux/<dir>/noctalia.toml ([widget.net_rx]/[widget.net_tx] interface)
• $HOME state that must survive: hosts/<dir>/preservation.nix (tmpfs root; 12kingdoms-shoukei imports hosts/idols-ai/preservation.nix)
• Theme (catppuccin), fonts: home/base/core/theme.nix, modules/nixos/desktop/fonts.nix
• Session, portal, and systemd wiring: modules/nixos/desktop/**, home/linux/gui/base/xdg/

Noctalia's merge order and [include] are in home/linux/gui/base/README.md. A per-host difference goes in that host's override file, not in the shared baseline.

2. Edit and validate

niri validate                       # the live config and its whole include graph
noctalia config validate            # the merged config, as the running shell loads it
noctalia config validate ./home/linux/gui/base/noctalia/config/config.toml   # one file

Validate the live Niri config, not the repo copy: config.kdl includes ./niri-hardware.kdl, which only the host module places in ~/.config/niri/, so niri validate -c <repo path> fails on the missing include.

Confirm a file is live before trusting a hot reload:

readlink -f ~/.config/niri/config.kdl      # must end in ~/nix-config/...
readlink -f ~/.config/noctalia/config.toml

~/.config/... points at a store path that is itself a symlink back into the repo. If it resolves to a plain store file, it is not live and the change needs just niri.

If an edit does not show up:

• niri msg action load-config-file forces a Niri reload.
• noctalia config export prints the merged config that actually won; diff it against your edit.
• ~/.local/state/noctalia/settings.toml loads last. A value saved through the Settings UI, or left over from an experiment, silently beats config.toml.