Skip to content
nMaax
dotfiles
Public

About

CachyOS + Hyprland + Noctalia = ❤️‍🔥

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

🥮 dotfiles

Personal dotfiles and system configurations, just the way I like it.

These dotfiles are heavily based on CachyOS (not just Arch), specifically the various packages that Cachy ships with its own base installation (fish, various KDE bloat, etc.).

Ideally, you should have installed CachyOS selecting Hyprland during the Calamares installation. If you didn't, 🥮 will install everything needed, but some manual changes could be necessary (e.g., enabling noctalia-greetr)

Managed using chezmoi. Code written with the help of Gemini, Claude, and Copilot.

Installation

Warning

This is NOT a run-and-forget installation. The install script will prompt you at several points. Keep an eye on the terminal throughout the entire process.

  1. Prepare your ~/.config/chezmoi/chezmoi.toml configuration file
[data]
  name = "uname"
  email = "you@example.com"
  tailscale_authkey = "tskey-auth-XXXXXXXXXXXXX" # "" installs Tailscale without logging in; false skips it entirely
  nordvpn_authkey = "nvpnkey-auth-XXXXXXXXXXXXX" # "" installs NordVPN without logging in; false skips it entirely
  mega_authkey = "megakey-auth-XXXXXXXXXXXXX" # "" installs MEGA without logging in; false skips it entirely
  gaming = true # false to avoid installing Steam, Mango, OpenRGB, etc.
  coding = true # false to skip dev tooling: Neovim, VS Code, lazygit, nodejs, etc.
  ai_dev = true # false to skip AI dev tools: CUDA, ROCm, Ollama, etc.
  agents = true # false to skip AI agents: Claude Code, Antigravity, OpenCode, Codex, etc.
  media = true # false to skip kdenlive, OBS, EasyEffects, Spotify, etc.
  office = true # false to skip LibreOffice, KeePassXC, qBittorrent, CUPS printing, etc.
  communication = true # false to skip Telegram, Signal, Discord, Element, etc.
  plugins = true # false to skip Hyprland plugins (hyprpm, scrolloverview)

During install, you will have the option to automatically wipe tailscale_authkey / nordvpn_authkey / mega_authkey from ~/.config/chezmoi/chezmoi.toml right after their use. Leaving any of them as "" still installs and enables that integration, just without an auto-login; set it to false to skip installing it altogether.

  1. Install chezmoi and apply the dotfiles
pacman -S chezmoi
chezmoi init --apply nMaax

Warning

ddcutil will be installed, which may cause instability with certain monitors. You can remove it via sudo pacman -Rns ddcutil if you encounter any issues.

Note

During log-in in the greeter, choose systemd-owned Hyprland (Hyprland (uwsm-managed)) instead of the plain one, to ensure autostart scripts function correctly (e.g. cachy-update tray icon).

Handling missing polkit agent password prompt in CachyOS Hello

If you would like to tweak CachyOS before running 🥮, but CachyOS Hello won't accept your password on a Hyprland-only installation (i.e., no Plasma), no polkit agent is likely running. You must ensure one is running so CachyOS Hello can trigger the authentication pop-up required to apply your changes.

To fix, do the following:

  1. Open your autostart config: vim ~/.config/hypr/lua/autostart.lua.

  2. Add this line inside your hl.on("hyprland.start", function() ... end) block (or anywhere at the bottom):

    hl.exec_cmd("/usr/lib/polkit-kde-authentication-agent-1")

    🥮 itself uses hyprpolkitagent (/usr/lib/hyprpolkitagent/hyprpolkitagent), installed during the apply, so this is only a stopgap for the first run.

  3. Save and restart Hyprland (Super + M or just log out and log back in).

  4. Now you should be able to tweak cachy as you like, and proceed with 🥮 installation.

Post-Installation

Keyring (KWallet)

KWallet is the password manager of choice in 🥮, due to the already wide presence of KDE ecosystem tools by CachyOS itself. The install scripts pull in the kwallet/kwalletmanager/kwallet-pam packages automatically, but PAM auto-unlock at login is not configured out of the box for the Noctalia greeter (greetd) — KWallet stays locked at session start, and unlocks via a one-time manual password prompt the first time an app needs a secret each session. Electron apps relying on the Electron safe-storage feature may still show their own separate prompts regardless.

If you'd rather have KWallet auto-unlock at login, you'll need to patch /etc/pam.d/greetd yourself with the same pam_kwallet5.so lines KDE ships for SDDM (see the Arch Wiki link below). Whether or not you do, when you're first prompted to create a wallet, use these settings so auto-unlock (now or later) actually works:

  • Name: kdewallet (the default; any other name will not be unlocked automatically by PAM)
  • Encryption: Blowfish (required for kwallet-pam auto-unlock; GnuPG encryption is incompatible)
  • Password: your current user login password (PAM unlocks the wallet by matching it against the login password)

Further information can be found at Arch Wiki: KDE Wallet and Electron Safe Storage Info.

SSH

The install script enables both sshd and the user-level ssh-agent automatically. But you still need to create a key pair and distribute your public key wherever you want to authenticate. Here are some common procedures you may want to do:

Generating a key

ssh-keygen -t ed25519 -C "axew"

Accept the default path (~/.ssh/id_ed25519) and optionally choose a passphrase. The new key is picked up automatically by the running ssh-agent.

Connecting to GitHub

  1. Copy your public key to the clipboard:

    cat ~/.ssh/id_ed25519.pub | wl-copy

  2. Go to GitHub → Settings → SSH and GPG keys → New SSH key, paste it and save.

  3. Test the connection:

    ssh -T git@github.com

    You should see: Hi <username>! You've successfully authenticated…

Note

You could be prompted to either create a new wallet, or to unlock the current one, refer to the above section for details.

  1. Tell Git to use SSH for GitHub remotes (optional, but recommended):

    git config --global url."git@github.com:".insteadOf "https://github.com/"

Connecting to another machine

Copy your public key to the remote host (replace user@host with your remote target machine):

ssh-copy-id user@host

Or manually append ~/.ssh/id_ed25519.pub to ~/.ssh/authorized_keys on the remote.

Optionally, create or edit ~/.ssh/config to define shortcuts:

Host myserver
    HostName 192.168.1.10
    User myuser
    IdentityFile ~/.ssh/id_ed25519

Then connect simply with ssh myserver.

GRUB

If you do use GRUB and want CachyOS's themed boot menu replaced with plain console text, run:

sudo sed -i 's|^GRUB_THEME=|#GRUB_THEME=|' /etc/default/grub
sudo sed -i 's|^#GRUB_TERMINAL_OUTPUT=console|GRUB_TERMINAL_OUTPUT=console|' /etc/default/grub
sudo grub-mkconfig -o /boot/grub/grub.cfg

Theming

Noctalia presents a standard approach to sync apps colorschemes with its own theme, each app requires its own procedure, part of it can be automated via code, and some other not. Further information can be found in official Noctalia documentation.

You can retrieve the list of apps on which automatic theming is set in the Noctalia settings themselves. Note, however, that some of those may still require some in-app manual intervention; below are some steps you shall take to complete the theming:

GTK and Qt

  • qt5ct (qt5ct command): Set Color scheme to noctalia, General font to SF Pro, Fixed-width font to CaskaydiaCove Nerd Font Mono
  • qt6ct (qt6ct command): Same as above.
    • Qt theming via qt6ct with QT_QPA_PLATFORMTHEME has already been set in Hyprland config files for environment variables (~/.config/hypr/lua/env.lua).
  • GTK (nwg-look): Set the general font to SF Pro Regular, then ensure Preferences > .config/gtk-4.0 is disabled; eventually, clear it if you found it enabled.
    • adw-gtk3 + prefer-dark was already applied via gsettings during the install script.
  • GTK apps will automatically fetch the color scheme from the above, while Qt apps must be configured separately by going into app settings and finding the colorscheme item.

Specific apps

  • Zen Browser: Open about: config → set toolkit.legacyUserProfileCustomizations.stylesheets to true; then open Settings → General → set Website Appearance to Auto; finally, restart Zen Browser.
  • Discord: Open Equibop → Settings → Themes → enable one of the two Noctalia themes.
  • VSCode: Install the NoctaliaTheme extension from the marketplace, then select it via Ctrl+Shift+P → Preferences: Color Theme.
  • Telegram: Open Settings → Chat Settings → scroll to the bottom and enable the custom color theme.
  • Steam: Install Material-Theme and add it in Millenium Settings > Theme, then click the three dots > configure > style > colors > select Matugen in the theme color dropdown.
  • Heroic Games Launcher: Settings → Advanced → set Custom Themes Path to ~/.config/heroic/themes, then select matugen from the theme dropdown. One-time; the generated CSS updates in place on further theme changes.
  • Prism Launcher: Settings → Appearance → Theme → select Matugen. One-time; the generated theme JSON updates in place on further theme changes.
  • All other enabled apps (btop, cava, ghostty, starship, hyprland, kcolorscheme, neovim, yazi) apply fully automatically; no action needed.

Note

If some apps do not properly fetch the color scheme even after having followed the noctalia guidelines, try to disable and re-enable them, as well as changing the color scheme as a whole.

Furthermore, you can install other themes for apps yourself; have a look at:

🥮 also supports linux-wallpaperengine! If you installed Steam you can see how to set it up and the related plugin

Browsing

The stuff that I usually use during my browsing experience is completely optional and up to your preference; do what you want with them:

Eventually consider also

Furthermore, here is a list of some good misc websites for assets in case you wanted to customize 🥮:

Spicetify extensions

Other stuff I use on Spicetify, I warmly advice is to use the marketplace as much as possible to install them! Spicetify and the Spicetify marketplace are automatically installed with 🥮.

If you want to re-run just the Spicetify setup without chezmoi apply, run:

~/.local/bin/spicetify-setup.sh
  • Spicy Lyrics (instead of Beautiful Lyrics, which seems to be deprecated!)
  • Global Stats for songs, to fetch info on different songs.
  • Shuffle+ for a Fisher-Yates randomization with zero bias.
  • Lucid Theme (instead of the Confy default one, tho this one looks quite heavy, bloated, and dirty, ngl.)

Warning

Disable Comfy theme via spicetify cli if you want to install a different one! Run the following:

spicetify config current_theme " "
spicetify apply

Gaming

Of course 🥮 is designed with gaming in mind too; 🥮 will apply some common installations and tweaks when gaming = true is set in chezmoi.toml. For more details, visit the CachyOS Gaming Wiki. Here is quick guidance to complete your gaming experience:

The sched-ext scheduler is set to scx_lavd in Gaming mode (/etc/scx_loader/config.toml, scx_loader enabled at boot). Check it with scxctl get, or change it from SCX Manager. Shader caches (NVIDIA and Mesa) are raised to 12 GB in ~/.config/environment.d/gaming.conf, which also sets globally: PROTON_DLSS_UPGRADE=1 and PROTON_NVIDIA_LIBS_NO_32BIT=1 (Proton-CachyOS only), NVIDIA's DLSS overrides (PROTON_ENABLE_NGX_UPDATER + DXVK_NVAPI_DRS_NGX_DLSS_*, any Proton; set one to off in a game's launch options to opt out), AMD's FSR4_UPGRADE=1 (RDNA4) and ENABLE_LAYER_MESA_ANTI_LAG=1 (layer installed on AMD by the gaming script), and DXVK_HUD=0.

Launch Options

Everything else is global in gaming.conf, so every game only needs the game-performance wrapper:

  • Steam: game-performance %command% in the game's launch options.
  • Heroic: Settings -> Game Defaults -> Advanced -> Wrapper, game-performance with empty arguments (and in each game with its own settings).
  • Lutris: game-performance as Command prefix under System options.

Warning

Native Wayland is opt-in per game with PROTON_ENABLE_WAYLAND=1 (Proton-CachyOS only). If you encounter a black screen, it probably is a conflict between direct scanout and the native Wayland compositor for the game. In such a case, drop it or disable direct_scanout in Hyprland settings.

Tip

NVIDIA Smooth Motion (RTX 40+, Vulkan/DXVK only): add NVPRESENT_ENABLE_SMOOTH_MOTION=1 per game for driver-level frame generation. Worth it on single-player games that are FPS-locked (e.g. 60 FPS caps) or CPU-bound, with no native frame gen, running at ~60-120 FPS. Skip it for competitive games, games with native DLSS FG, or games already at your refresh rate. If overlays glitch, add NVPRESENT_QUEUE_FAMILY=1.

For Lutris specifically, remember to enable Disable Lutris Runtime and Prefer system libraries

Gaming mouse

Mouse acceleration is flat for the device named in ~/.config/hypr/lua/input.lua (default realtek-mchose-l7-pro+). Set yours with the name from hyprctl devices.

Steam/Proton Settings

  • Compatibility: Keep Valve's Proton (latest stable or Experimental) as the global default in Steam -> Settings -> Compatibility. Switch single games to proton-cachyos-slr (Properties -> Compatibility) when they need its fixes/FSR, or when EAC/BattlEye refuses to log in. Lutris/Heroic: use proton-cachyos-slr.
  • Pre-caching: If using Proton-CachyOS, navigate to Steam -> Settings -> Downloads and UNCHECK:
    • "Enable Shader Pre-caching"
    • "Allow background processing of Vulkan shaders"

Note

If in-game videos don't play or show color bars, run steam steam://unlockh264/ once, wait for it to load, then restart Steam normally.

Temporarily switching to Hyprland on a deckified/gamescope boot

On CachyOS handheld images that boot into gamescope (Big Picture) and fall back to Plasma via Steam's "Switch to Desktop", the boot session is controlled by steamos-session-select, which writes to /etc/plasmalogin.conf.d/zz-steamos-autologin.conf through /usr/lib/steamos/steam-set-session.

The steamos-session-select wrapper only recognizes plasma/gamescope as targets, but the underlying helper accepts any .desktop name — including hyprland.desktop / hyprland-uwsm.desktop once 🥮 is installed.

To boot into Hyprland instead of Plasma while keeping "persistent" desktop mode:

steamos-session-select persistent # remember last-used session across boots
sudo /usr/lib/steamos/steam-set-session hyprland-uwsm.desktop # set hyprland (UWSM) as main session

Then reboot, and Hyprland will launch.

To revert to stock handheld behavior (always boot to Big Picture), run:

steamos-session-select oneshot

Streaming (P2P)

If you are not satisfied with the Wayland screenshare when streaming games on your Electron app (e.g., Discord), then 🥮 brings some plugins to stream your games with low latency and low added input latency on the game. Namely using obs-vkcapture, lib32-obs-vkcapture, and obs-pipewire-audio-capture.

  1. Launch your game, so its audio and video hooks are active in your system.
  2. Open OBS Studio. Under the Sources dock, click the + icon.
  3. Add a Game Capture (Vulkan/OpenGL) source. Leave its properties at default; it will automatically hook into your game's engine.
  4. Click + again and add an Application Audio Capture (PipeWire) source.
  5. Inside its properties, find the Application dropdown menu and select wine64-preloader (this represents your Steam Proton / Wine game process).

Because you are explicitly capturing the game audio now, you must turn off OBS's global desktop capture so your friend doesn't hear everything twice:

  • Go to Settings $\rightarrow$ Audio.
  • Under Global Audio Devices, change Desktop Audio to Disabled. Click Apply.

To drop your hardware encoding delay down to less than 15 milliseconds, you need to adjust your video framing and reconfigure the NVIDIA NVENC encoder pipeline.

On the left menu, select the Video tab. Do not use the "Rescale Output" checkbox in the encoder menu; handle it here instead:

  • Base (Canvas) Resolution: Match this to your monitor's native resolution (e.g., 2560x1440).
  • Output (Scaled) Resolution: Set this to 1920x1080 (1080p is the sweet spot).
  • Downscale Filter: Bicubic (Sharpened scaling, 16 samples).
  • Common FPS Values: 60.

Go to the Output tab and flip the Output Mode at the very top from Simple to Advanced. In the Streaming tab, mirror these exact specifications:

Setting Value to Select / Type Description
Audio Encoder FFmpeg Opus Enforced by WebRTC for instant, crisp sound.
Video Encoder NVIDIA NVENC H.264 Uses your GPU hardware so your game doesn't lag.
Rate Control CBR Delivers a smooth, predictable data stream.
Bitrate 6000 Kbps Pristine quality for 1080p60 without network bloating.
Keyframe Interval 1 s Allows the web player to recover instantly from dropped packets.
Preset P1: Fastest (Lowest Latency) Bypasses complex frame analysis to prioritize speed.
Tuning Low Latency Cuts out internal encoder buffer queues.
Multipass Mode Single Pass Processes the frame once instead of twice.
Profile baseline Strips out heavy compression loops that cause player buffering.
Look-ahead 🔲 Uncheck Prevents the GPU from processing future frames in advance.
Adaptive Quantization 🔲 Uncheck Eliminates extra algorithmic calculation passes.
B-Frames 0 Most Important: Sends frames out instantly as they render.

Finally, go to the Advanced tab on the left sidebar. Under General, change Process Priority from Normal to Above Normal or High. This stops the Linux kernel from starving OBS of resources when your game hits an intense scene.

Now we are ready to run the Meshcast Stream.

  1. Open your web browser and navigate to Meshcast.io.

  2. Scroll to the Stream using WHIP section, type a unique ID, select your closest regional server location, and click the link generation button.

  3. Meshcast will hand you a WHIP URL that looks similar to this: https://cae2.meshcast.io/whip/MadaMada1234.

  4. In OBS, go to Settings > Stream.

  5. Set Service to WHIP.

  6. Split your Meshcast link across the two input boxes like this:

    • Server: https://cae2.meshcast.io/whip/
    • Bearer Token: MadaMada1234 (The unique string at the very end of your link) (or just skip the token and put the whole link in the server field)

  7. Click Apply and OK.

Now you can copy the Watch Page Link provided by the Meshcast interface (e.g., https://meshcast.io/view.html?geo=cae2&id=MadaMada1234) and send it over to your friends.

Hit Start Streaming in OBS. That's it :)

📝 TODOs

  • Prepare 2K-4K WALLHACK Wallpapers -> Make a release for dotfiles-assets if files are too large
  • Once everything is finished, add screenshots and videos in this README

New features to try

  • Try Hyprglass (add it to HYPRPM_PLUGINS)
  • Try HyprMon (hyprmon-bin) for multi-monitor layout and profiles, alongside a slimmed-down monitors.lua

For the future

  • Try HDR gaming: needs a Proton with native Wayland + HDR (GE-Proton: PROTON_ENABLE_WAYLAND=1 PROTON_ENABLE_HDR=1, Valve's Proton can't) and a 10-bit HDR monitor config (bitdepth = 10, cm = edid, render:cm_auto_hdr), see Hyprland #11083. The AOC already runs at 10-bit with direct scanout working
  • Try the ADIOS I/O scheduler once it's stable (CachyOS defaults NVMe to kyber)
  • Enhance assets by introducing a GitHub CI action that autogenerates a README with a gallery, like dharmx
  • Generalize for pure Arch by reproducing what Cachy installs, including fundamentals like Bluetooth, NetworkManager, fish, CachyOS fish setup, GPU drivers, etc.

About

CachyOS + Hyprland + Noctalia = ❤️‍🔥

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages