A Note From Me

As previous dual-boot cachyos user I wanted to switch to fully use linux in my daily life. Someone mentioned he started newly using nixos and well here we are. This rice is now built over a period of 5 months until I said it is good and bug free to use.

In the first few weeks, I managed to like break the system three times a day and I was told nixos is not breakable ... only via live usb the pc was fixable as I edited the hardware-configuration.nix file lol stupid beginner mistake right? And the refind/grub customization caused that too but totally worth it.

---

Screenshots

---

Boot Animations

Generate GIFs from the MP4s: for f in assets/plymouth/*/; do name=$(basename $f); ffmpeg -i "$f$name.mp4" -vf "fps=15,scale=400:-1" "$f$name.gif"; done

dotted

flower

icy

matrix

---

Bootloaders

GRUB2

rEFInd

---

OS	NixOS 25.11
WM	Hyprland · KDE Plasma 6
Shell	Zsh · Powerlevel10k
Terminal	Ghostty
Bar	Caelestia Shell
Browser	Zen Browser
Editor	Neovim (LazyVim) · Antigravity · Zed
File Manager	Yazi · Dolphin
Theme	Sweet Dark · Kvantum
Icons	Papirus-Dark · Slot-Dark · Vivid-Dark
Cursor	Sweet Cursors
Login	SDDM · Sonomatic
Boot	Plymouth · custom MP4 themes
Disk	Btrfs · LUKS · Impermanence

---

Structure

NixOS/
├── flake.nix
├── deploy.sh                    # Install & rebuild helper
├── hosts/
│   ├── common.nix               # Shared system config
│   ├── disko-config.nix         # Disk layout (LUKS + Btrfs)
│   ├── muddyblack/              # Full desktop
│   └── muddyblack-lite/         # Lightweight (VM / testing)
├── modules/
│   ├── nixos/                   # System-level modules & features
│   └── home-manager/            # User environment
├── pkgs/                        # Custom packages & overlays
├── assets/                      # Wallpapers, sounds, themes, icons
└── dev-shells/                  # Language dev environment templates

---

Install

No hardware-configuration.nix in this repo — disks are partitioned at install time via Disko. You can install on a running system or from the NixOS minimal ISO.

Disk layout — the disko config works on any drive. deploy.sh will prompt you for your disk device (e.g. /dev/sda, /dev/nvme0n1) or you can pass --device to skip the prompt. Partition sizes for dual-boot (--win-size, --shared-size) are also configurable — see bash deploy.sh help for all flags.

Try in a VM first (from any machine with Nix)

nix build .#nixosConfigurations.muddyblack-lite.config.system.build.vm
./result/bin/run-muddyblack-lite-vm

Fresh install from a live ISO

sudo su
git clone https://github.com/Muddyblack/NixOS /mnt/NixOS
cd /mnt/NixOS
bash deploy.sh fresh                          # prompts for disk device
# or: bash deploy.sh fresh --device /dev/nvme0n1 --no-dual-boot

Remote install via nixos-anywhere

git clone https://github.com/Muddyblack/NixOS
cd NixOS
bash deploy.sh fresh --remote root@<ip> --device /dev/sda

Day-to-day rebuild:

upnix

KDE only or Hyprland only: Both WMs are configured by default and switchable at the login screen. Remove the one you don't want from modules/home-manager/home.nix:

./plasma-settings.nix   # KDE Plasma
./hyprland.nix          # Hyprland

---

Shell & Tools

Powered by Zsh + Powerlevel10k, with modern CLI replacements throughout:

Tool	Replaces	Notes
zoxide	cd	Frecency-based directory jumping
eza	ls	Icons, git info; auto-runs on cd
yazi	file manager	Terminal file browser
fzf + fzf-tab	tab completion	Fuzzy completions + history search
ripgrep	grep	Aliased as grep
fd	find	Aliased as find
btop	top	Aliased as top
gping	ping	Graphical, aliased as ping
xh	curl	Aliased as curl

Reconfigure the prompt:

p10k configure

---

Usage

Generations & rollback:

gen           # list all generations
rollback N    # switch to generation N
gcnix         # garbage collect (keeps last 5 generations)

All key aliases

Command	Does
upnix	Rebuild & switch (plays sound on done)
update	nix flake update
gen	List NixOS generations
rollback N	Roll back to generation N
gcnix	Garbage collect
ll	eza with icons & git info
vim	nvim
top	btop
grep	ripgrep
find	fd
ping	gping (graphical)
curl	xh
lg	lazygit
gs ga gc gp	git status / add / commit / push

Keybindings (Hyprland)

Shortcut	Action
Super + Return	Terminal (Ghostty)
Super + E	File manager (Dolphin)
Super + Q	Close window
Super + F	Fullscreen
Super + Shift + S	Screenshot (region)
Super + 1-9	Switch workspace
Super + Shift + 1-9	Move window to workspace
Super + −	Toggle special workspace

KDE Plasma layout:

Desktop widgets and panel layout are managed by plasma-manager via modules/home-manager/plasma-settings.nix. After editing and running upnix, Plasma needs a layout rebuild to pick up changes:

systemctl --user start plasma-layout-rebuild

This backs up your current layout, wipes Plasma's cache, and re-applies everything from config. Use it whenever widgets drift or don't appear after a rebuild.

---

Secrets

Personal secrets (e.g. the :mail espanso snippet) are stored encrypted in secrets/secrets.yaml via sops-nix. SOPS is opt-in — set features.sops.enable = false if you don't need it; forks build fine without it.

First-time setup on a new machine

One command generates your age key, updates .sops.yaml, and opens the editor:

./deploy.sh sops-setup

Add your secrets (see secrets/secrets.yaml.example for the schema), then enable and rebuild:

features.sops.enable = true;

upnix

Day-to-day secret management

secrets edit    # edit encrypted secrets
secrets rotate  # re-encrypt after adding a new key to .sops.yaml

Adding a new secret:

1. secrets edit → add a key
2. Declare it in modules/nixos/features/sops.nix:

   sops.secrets.my-secret = { owner = username; mode = "0400"; };

3. Reference as a file path: /run/secrets/my-secret

---

Credits

Project	Author
Caelestia Shell	caelestia-dots
Sweet Theme & Cursors	EliverLara
Sonomatic SDDM	phob1an
Illusion Plymouth Splash	dgudim
Boot Animations (Google Veo)	Google DeepMind
Vivid Plasma Themes	L4ki
Slot Icon Theme	L4ki
Colorful Icon Theme	L4ki
Iridescent Plasma Style	ddh4r4m
Utterly Round Plasma Style	HimDek
Overview Widget	HimDek
Modern Clock Widget	prayag2
Netspeed Widget	dfaust
Plasma Audio Visualizer	muddyblack
Audio Wave Widget	zayronxio (inspiration)
Grub2 Themes	vinceliuice
rEFInd Theme	evanpurkhiser
Sly-Harvey/NixOS	Sly-Harvey
home-manager	nix-community
disko	nix-community
impermanence	nix-community
sops-nix	Mic92
plasma-manager	nix-community