cachyos/docs/desktop/README.md

Desktop

The desktop layer on CachyOS: the Umbriel compositor, the Noctalia shell, fontconfig, and default applications.

Note

Role gating

.chezmoiignore.tmpl skips the desktop layer unless the machine runs Linux and its role is desktop or laptop. The gated targets are ~/.config/umbriel, ~/.config/noctalia, ~/.config/fontconfig, ~/.config/mimeapps.list, ~/.config/xdg-terminals.list, ~/.config/systemd, ~/.local/bin/agent-root, ~/.local/bin/kitty-day-save, ~/.local/bin/umbriel-launch, ~/.local/bin/umbriel-smart-move, ~/.local/bin/umbriel-float-square, ~/.local/bin/cp-appid, and ~/.local/bin/projects-sync. On the server role these are not applied.

The session is Umbriel, Noctalia's scrolling compositor, with Noctalia as the only session process: it provides the bar, launcher, clipboard history, notifications, polkit agent, and OSD.

Page	Covers
Umbriel	~/.config/umbriel (session, layout, outputs, rules, scratchpads, binds), umbriel-launch, umbriel-smart-move, and umbriel-float-square
Fonts and default apps	~/.config/fontconfig/fonts.conf, ~/.config/mimeapps.list, the Victor Mono Nerd Font packages

The Noctalia config itself (~/.config/noctalia) is the prdlk/noctalia external, see externals.

Packages

.chezmoidata/packages.yaml declares the desktop packages under packages.arch.desktop. .chezmoiscripts/run_onchange_before_10-packages.sh.tmpl installs them only when the role is desktop or laptop:

Source	Packages
pacman	noctalia (the CachyOS build where that repo is configured, else extra), polkit, xdg-user-dirs, xdg-terminal-exec, Wayland utilities (wl-clipboard, cliphist, wtype, ydotool, grim, slurp, pamixer, brightnessctl, libnotify), the bound apps (nautilus, imv, mpv, evince, chromium, obsidian), and strata's runtime deps
AUR via yay/paru (a sync repo wins when it has the name)	tldraw-offline-bin, bibata-cursor-translucent, umbriel-git (with xdg-desktop-portal-umbriel-git), herdr-bin, voxtype-bin, and the desktop apps beeper-bin, fastmail, 1password, brave-origin-bin, claude-desktop, spotify

AUR names that an installed package already provides are skipped; with no yay or paru the script bootstraps yay first. strata, the default file manager, comes from its own installer in 15-tools. See chezmoi scripts for the full install flow and packages.yaml for the complete lists.

Thunderbolt eGPU (compute only)

The RTX 5060 Ti in a USB4 enclosure (Minisforum TBGAA, bolt policy iommu) is for CUDA only: AI models, never displays or rendering. Every display hangs off the Radeon 8060S iGPU (PCI c4:00.0). Packages: linux-cachyos-nvidia-open, nvidia-utils, cuda, opencl-nvidia. Nothing in this section is managed by chezmoi except the session environment.

File	Setting	Why
/etc/default/limine	no pci=nommconf, no pcie_aspm=off; pcie_aspm.policy=performance instead	The first two make Linux skip the PCIe _OSC control request (not requesting OS control; OS requires [ExtendedConfig ASPM …]). Then pciehp never binds the USB4 bridges 00:01.1/00:01.2, and the enclosure authorizes while the GPU never shows up in lspci. pcie_aspm.policy=performance disables ASPM without that side effect. Run limine-update after editing.
/etc/modprobe.d/nvidia-egpu.conf	install nvidia_drm /bin/true, install nvidia_modeset /bin/true, NVreg_DynamicPowerManagement=0x00, NVreg_PreserveVideoMemoryAllocations=0	Without nvidia_drm there is no /dev/dri node for the eGPU, so no compositor, GBM, or VA-API driver can open it. CUDA needs only nvidia and nvidia_uvm. nvidia-suspend.service is not enabled, and with PreserveVideoMemoryAllocations=1 suspend fails while the eGPU is bound.
/etc/modprobe.d/thunderbolt-egpu.conf	options thunderbolt host_reset=0 clx=0	host_reset=0 keeps the firmware-built PCIe tunnel at boot; with the default reset the tunnel drops while nvidia initialises the card (Xid 79, GPU stuck until reboot). clx=0 keeps the USB4 lanes out of CL1/CL2 low-power states.
/etc/systemd/system/nvidia-egpu-powercap.service, /etc/udev/rules.d/62-nvidia-egpu-powercap.rules	nvidia-smi -pm 1 -pl 150 -lgc 210,1800 when the nvidia module loads	Caps the card at 150 W / 1800 MHz before anything can load it.
/etc/udev/rules.d/61-nvidia-compute.rules	nvidia-modprobe -c0 -u when the nvidia module loads	nvidia-utils' own rule creates /dev/nvidia* when nvidia_drm loads, and that module never loads here.
no /etc/modules-load.d entry	none	udev loads nvidia by modalias when the GPU reaches the bus, at boot or on hotplug.

nouveau is blacklisted by nvidia-utils (/usr/lib/modprobe.d/nvidia-utils.conf). Without that blacklist, nouveau binds the card, the NVIDIA driver reports GPU … is already bound to nouveau, and a link drop deadlocks pciehp in nouveau's GSP teardown.

Session side: conf.d/10-env.fish sets __EGL_VENDOR_LIBRARY_FILENAMES (Mesa) and VK_DRIVER_FILES (RADV), see fish. Umbriel starts through a fish login shell, so the compositor, Noctalia, and every app inherit them. Without them, glvnd and the Vulkan loader load the NVIDIA vendor libraries into every process, and those processes hold /dev/nvidiactl.

Never expose nvidia_icd.json to LM Studio. When its engine survey reaches the eGPU through NVIDIA's Vulkan driver, the card falls off the bus (Xid 79) and the machine hard-resets. The survey runs when the app starts and when the llmster daemon starts, and any lms command starts that daemon.

Check: nvidia-smi lists the card, and fuser -v /dev/nvidia* shows only CUDA processes. A short CUDA kernel (vector add) runs correctly.

Status: unusable under load on the Flow Z13 (GZ302EA, BIOS 311)

The moment a model starts inference on the eGPU, the platform hard-resets with x86/amd: Previous system reset reason [0x08000800]: an uncorrected error caused a data fabric sync flood event, no Xid, no log tail. Firmware grants no AER/DPC to the OS, so a tunnel fault under load becomes a full reset. Everything above was tested one variable at a time on 2026-10-17 and none of it changed the outcome: CUDA or Vulkan engine, model size (27B and 12B), both USB4 ports, dock wiring per the DEG2 manual on a 650 W PSU, ASPM off, clx=0, 150 W power cap, KMS loaded or not, and the previous OS install with stock NVIDIA config. The same models run fine on the iGPU with the dock unplugged, so the fault is the Z13's USB4 PCIe path under GPU load, not the SoC alone. Other GZ302EA owners report the same reset code under sustained load (Level1Techs) and eGPU trouble on this platform (ROG forum). Untested: a shorter certified 40 Gbps cable, the same dock and card on another host, Windows. LLM work runs on the 8060S (Vulkan/ROCm, unified memory) until one of those changes the picture.