Skip to content
GNARUSGNARUS

Environment

GNARUS is a complete desktop, ready to use, focused on Hyprland. The desktop configuration lives in the gnarus repository and is packaged as the gnarus Arch Linux package.

The package installs read-only defaults under /usr/share/gnarus and the optional gnarus-setup copy helper under /usr/bin. It never writes to $HOME.

Component packages

Section titled “Component packages”

The desktop is split into focused packages, all built by gnarus-pkgbuild and published to the same repository:

Package Owns
gnarus Desktop configuration under /usr/share/gnarus and the optional /usr/bin/gnarus-setup helper.
gnarus-session Session launchers /usr/bin/gnarus-session, /usr/bin/gnarus-start, /usr/bin/gnarus-tty and /usr/share/wayland-sessions/gnarus.desktop.
gnarus-appearance Shared wallpapers under /usr/share/backgrounds/gnarus and bundled fonts under /usr/share/fonts.
gnarus-storage The removable-storage Waybar module (binary, config and themes).
gnarus-calendar The native calendar popup for Waybar (binary, config and themes).
gnarus-greeter The greetd greeter integration.

Installing gnarus pulls in the other component packages as dependencies.

Desktop composition

Section titled “Desktop composition”
Area Files Purpose
Session config/hypr/hyprland.lua Main compositor configuration, keybindings, workspace behavior, rules and startup commands.
Setup bin/gnarus-setup Optional helper that copies packaged defaults into the user’s config directory for customization.
Waybar config/waybar/config.jsonc, config/waybar/style.css Top bar with workspaces, media, window title, tray, system state and GNARUS modules.
Sidebar config/quickshell/sidebar-right/ Quickshell panel for settings, system state, calendar, network, volume, brightness and power controls.
Launchers config/rofi/, config/wofi/ Application launchers, menus and themed command surfaces.
Terminal and TUI apps config/kitty/, config/yazi/, config/superfile/, config/btop/, config/bottom/ Terminal defaults, file managers and system monitors.
Notifications and logout config/dunst/, config/wlogout/ Notification styling and power/logout UI.

Session flow

Section titled “Session flow”

gnarus-session is the display-manager entry point. It prepares the environment and executes gnarus-start; it does not copy configuration into $HOME.

gnarus-start launches Hyprland with the appropriate GNARUS configuration. It uses $XDG_CONFIG_HOME/hypr/hyprland.lua when that user override exists, otherwise the packaged /usr/share/gnarus/hypr/hyprland.lua, and resets the graphical session identity to Hyprland so a display-manager greeter environment is not inherited.

gnarus-tty provides a manual TTY path for systems without a display manager. It registers a logind session, starts the D-Bus session bus, sets the Wayland/XDG environment and launches the same session.

Configuration model

Section titled “Configuration model”

GNARUS does not copy dotfiles into $HOME before the desktop can start. Runtime entrypoints use this priority:

$XDG_CONFIG_HOME/<app>  ->  /usr/share/gnarus/<app>  ->  upstream defaults

The session prepends /usr/share/gnarus to $XDG_CONFIG_DIRS while preserving existing directories such as /etc/xdg, so applications that support XDG system configuration discover packaged GNARUS defaults automatically.

gnarus-setup is optional. Use it only when you want to copy packaged defaults into ~/.config for customization:

Mode Behavior
--copy <app> Copies /usr/share/gnarus/<app> to ~/.config/<app>.
--copy-all Copies every packaged default.
--force Backs up an existing destination as ~/.config/<app>.bak-<timestamp> before copying.
--dry-run Prints the actions without changing files.
--repair Backward-compatible alias for --copy gnarus.

Once copied, files in $XDG_CONFIG_HOME are user-owned overrides and package upgrades never replace them.

Runtime state is stored in small files under ~/.config/gnarus/, such as .active-theme, .accent-color and .weather-location. The optional profile file enables TTY auto-start.

Hyprland

Section titled “Hyprland”

The main compositor file is config/hypr/hyprland.lua. It loads the active theme, accent color and spacing values before defining the session.

Notable defaults:

  • SUPER is the main modifier.
  • Layout is dwindle, with grouping enabled.
  • Keyboard layout defaults to br,us with grp:alt_shift_toggle.
  • Firefox is forced to Wayland through MOZ_ENABLE_WAYLAND=1.
  • Qt apps use the configured platform theme and Hyprland Qt style where available.
  • XWayland remains enabled for compatibility.

Hyprland helper scripts live under config/hypr/scripts/ and cover screenshots, power menu, wallpaper selection, cheatsheets, Waybar startup and the GNARUS Storage menu anchor.

Waybar

Section titled “Waybar”

GNARUS uses Waybar as the primary top bar. The default layout groups workspaces and media on the left, window context in the center, and system modules on the right.

Important modules:

  • hyprland/workspaces for workspace navigation.
  • mpris for media state.
  • network, memory, cpu, CPU/GPU temperature scripts and power profile status.
  • custom/storage, powered by gnarus-storage watch.
  • clock#date, which toggles the native calendar popup (gnarus-calendar) on click.
  • pulseaudio#input and pulseaudio#output with click and scroll controls.
  • tray for applications that expose status icons.
  • custom/settings, which toggles the Quickshell sidebar.

System-detail scripts live under config/waybar/scripts/sysinfo/; the auxiliary sysinfo view is configured by config/waybar/sysinfo.jsonc and config/waybar/sysinfo.css.

Quickshell sidebar

Section titled “Quickshell sidebar”

The right sidebar lives in config/quickshell/sidebar-right. It is a QML interface for repeated desktop actions rather than a decorative panel.

It includes cards for:

  • appearance and theme controls;
  • brightness and volume;
  • calendar;
  • keyboard layout;
  • network;
  • notifications;
  • power actions;
  • workspace spacing;
  • system information;
  • weather.

The Waybar settings button toggles this sidebar through the GNARUS taskbar script.

Themes

Section titled “Themes”

GNARUS ships eight theme families:

  • gnarus-dark
  • gnarus-dark-float
  • gnarus-dark-silver
  • gnarus-dark-silver-float
  • gnarus-light
  • gnarus-light-float
  • gnarus-slate
  • gnarus-slate-float

Theme files are mirrored across Hyprland, Waybar, Rofi, Dunst, Kitty, Btop, Bottom, Wlogout, Yazi, Superfile, Snappy Switcher and Qt color schemes. The active theme is applied by config/gnarus/sh/theme-switch.sh.

The accent color is handled separately by config/gnarus/sh/accent-switch.sh, so a user can change the accent without replacing the theme family.

Shared shell modules live under config/gnarus/sh/ and are loaded through bootstrap.sh, which exposes logging, paths, notification, JSON and Hyprland helpers to scripts.

Wallpapers and bundled fonts are owned by the gnarus-appearance package and referenced from system paths such as /usr/share/backgrounds/gnarus/.

Packaged paths

Section titled “Packaged paths”

The gnarus package installs:

/usr/bin/gnarus-setup
/usr/share/gnarus/

The gnarus-session package installs the session entrypoints:

/usr/bin/gnarus-session
/usr/bin/gnarus-start
/usr/bin/gnarus-tty
/usr/share/wayland-sessions/gnarus.desktop

gnarus-storage and gnarus-calendar are packaged separately and install their own binaries and system defaults. See Official Apps, Calendar and Removable Storage.