Hypeless

A Hyprland desktop for Debian Sid.

• Debian-native Hyprland. The Hyprland ecosystem comes straight from Debian's repositories, plugins included. Two pieces come from outside it: the Hyprspace workspace overview, which Debian does not package and whose upstream does not yet build against Hyprland 0.56, so it is compiled from a fork; and hyprshell, the Command-Tab window switcher, installed from its upstream x86_64 release.
• KDE without Plasma. Full KDE suite, made to work nicely outside a Plasma session.
• System-Wide Themes. Choosing a wallpaper recolors every pre-installed application. Consistent themeing across QT, GTK, Firefox, RetroArch, and more.
• Systemd controlled session. Every graphical application runs as a systemd user unit. Session state, logs, startup ordering, and failures are all inspectable with systemctl --user and journalctl --user.

Debian Sid (unstable) is currently the only Debian branch with a complete Hyprland ecosystem packaged in the official repositories. The long-term goal is to support Debian 14 Stable if the necessary packages are available.

Installation

Prerequisites

• The full install makes extensive system-wide changes and is intended for a clean system. On an existing system, use the dotfiles preset or the component picker to install only what you want (e.g. skip login and network). Anything the installer would overwrite is backed up to ~/.local/state/hypeless/backups/<timestamp>/ first.
• Ensure your computer's architecture is x86_64.
• Read install.sh and the modules in install/modules/.
• Verify you have a working internet connection.
• sudo is installed and the user running the script is a member of the sudo group.
• Do not run as sudo.

Steps

1. Promote a clean Debian 13 system to Debian Sid (required)

# Clone the repository
mkdir -p ~/Projects ~/.config
sudo apt install git
git clone https://forge.eriador.dev/dane/hypeless.git ~/Projects/hypeless

# Switch to Debian Sid sources (main, contrib, non-free, and non-free-firmware)
sudo rm /etc/apt/sources.list
sudo cp ~/Projects/hypeless/etc/apt/sources.list.d/debian.sources /etc/apt/sources.list.d/debian.sources

# Perform the full upgrade
sudo apt update && sudo apt full-upgrade -y
sudo reboot

2. Install NVIDIA Open Kernel Drivers (optional)

# Install kernel headers
sudo apt install linux-headers-$(uname -r)

# Install NVIDIA APT keyring
wget -P ~/ https://developer.download.nvidia.com/compute/cuda/repos/debian13/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i ~/cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt modernize-sources

# Install NVIDIA Open-Drivers
sudo apt -V install nvidia-open

rm ~/cuda-keyring_1.1-1_all.deb
sudo reboot

3. Run the installer and reboot when it finishes:

cd ~/Projects/hypeless
./install.sh

The installer opens an interactive menu. It has three sections:

• Presets: full (the complete system, pre-selected, makes system-wide changes) and dotfiles (avoids making system changes, still installs software, and configures the user; safer on an already-configured machine).
• Modules: every component individually toggleable, organized into groups.
• Flags: --link, --configs-only, --dry-run, and --no-backup toggles.

The installer is interactive only at the start and logs everything to ~/hypeless-install.log. Every file the installer replaces (including files under /etc) is first copied to ~/.local/state/hypeless/backups/<timestamp>/, mirroring its absolute path. Reboot after the script has finished running.

After the final reboot, log in through the tty1 login screen and ensure the selected session is Hyprland (uwsm-managed).

Installer options

Note: Running ./install.sh opens the interactive menu. Passing in flags skips the interactive menu and runs the install script with selected options.

Flag	Description
--profile NAME	Use a preset selection: full or dotfiles
--only LIST	Install only these modules (comma-separated), plus whatever they require
--skip LIST	Exclude these modules (comma-separated)
--list	List available modules and exit
-l, --link	Symlink user configs from the repo instead of copying them, so editing your live config edits the git checkout. System files under /etc and /usr are always copied.
--configs-only	Only deploy repo-managed user config files. No packages, no builds, no user, or system changes.
--dry-run	Print what the selected modules would install and deploy, then exit without changing anything
-d, --dotfiles PATH	Path to the hypeless repo (default: the directory the script lives in)
--no-backup	Don't back up existing files before overwriting them

CLI Installer Examples

# see what the dotfiles preset would do first
./install.sh --profile dotfiles --dry-run

# install Hypeless without gaming or communications
./install.sh --profile full --skip gaming,communication

# re-sync specific desktop configs, symlinked to the repo
./install.sh --link --configs-only --only hyprland,status-bar,notifications,theming

Usage

• Super + CTRL + K opens a searchable menu of every key binding. This is the best way to learn the desktop.

Some highlights:

Keys	Action
Super + CTRL + K	Keybindings Menu
Super + CTRL + Space	System theme picker
Super + Return	Terminal
Super + L	Toggle floating/dwindle window layout
Super + Space	App launcher
Super + Shift + Return	Browser
Super + Shift + F	File manager
Super + W	Close window
Super + Tab	Switch windows — hold Super, Tab moves the selection, release to focus
Super + [1–0]	Switch workspace
Ctrl + ← / →	Previous / next workspace
Ctrl + ↑	Workspace overview
Super + Ctrl + [1–0]	Move window to workspace
Super + S	Toggle scratchpad
Super + Shift + V	Clipboard manager
Super + ,	Notification center
Super + Escape	Lock screen

Launcher search (Super + Space) is intent-based: one box ranks apps, files, web searches and arithmetic (1+1, 10 km in miles) against each other, no prefixes needed. /, ., : and @ still force the provider list, files, symbols and web search directly, and arithmetic results copy with Return.

What the installer changes system-wide

For transparency, beyond installing packages and overwriting configs the script:

• Replaces /etc/pam.d/greetd, greetd-greeter, and hyprlock (KWallet/ksecretd auto-unlock)
• Purges GNOME Keyring (gnome-keyring, gnome-keyring-pkcs11, libpam-gnome-keyring) and blocks it from being reinstalled via an apt pin, replacing it with KWallet
• Makes NetworkManager the sole network + DNS manager: replaces /etc/NetworkManager/NetworkManager.conf, adds conf.d drop-ins, and masks networking.service (ifupdown)
• Installs an nftables (firewall) ruleset at /etc/nftables.conf, switches iptables and ip6tables to the nft backend, and adds a NetworkManager dispatcher script to keep the ruleset's LAN definition in sync
• Enables greetd, disables getty@tty1, and sets the default target to graphical
• Force-installs the pywalfox extension policy for Firefox via /etc/firefox/policies/policies.json, and the same extension for Thunderbird via /etc/thunderbird/policies/policies.json
• Enables Bluetooth and the SwayOSD libinput backend
• Loads the i2c-dev kernel module at boot (ddcutil DDC/CI brightness control)
• Loads the uinput kernel module at boot, adds a udev rule, and adds you to the input group (clipboard auto-paste)
• Adds you to the adm group, so the log viewer can read the system journal and /var/log instead of only your own messages
• Changes your login shell to zsh
• Patches plasma-kded6.service to initialize correctly outside of a full Plasma session
• Installs source-built/cloned tools and short-name wrappers to /usr/local/bin, and clones gazelle-tui into /opt
• Symlinks fdfind to /usr/local/bin/fd

Bonus Features

• Gaming RetroArch comes pre-configured out of the box, alongside the Heroic Games Launcher and Steam.
• Native Spotify Streaming Strawberry Music Player streams Spotify directly, no browser tab required.
• Hardened Firefox Betterfox's privacy/security user.js is applied automatically, and re-synced on every login even if Firefox switches its default profile out from under it.
• DDC Monitor Brightness External monitors are controlled over DDC/CI (ddcutil), so the brightness OSD and keys work on desktop displays, not just laptop panels.
• Clipboard Auto-Paste Clipse's clipboard history can auto-type an entry back out via a virtual input device, not just copy it to the buffer.
• Password Manager KeePassXC runs as the upstream AppImage until Debian packages catches up to 2.7.12, currently APT is 2.7.10.
• TUI Control Panels Bluetooth (bluetui), audio (wiremix), and networking (gazelle-tui) all get full-featured terminal UIs alongside their GUI counterparts.
• Instant Web Apps Turn any site into its own app window and launcher entry with one script (webapp-install "Name" https://example.com); Google Maps ships pre-added.

Software

Hypeless stands on the work of many other people. Core software that makes the desktop work:

Project	Role
Hyprland	Compositor, hypridle, hyprlock, hyprshutdown, hyprpolkitagent, hyprpicker
UWSM / app2unit	Session and app unit management
greetd + tuigreet	Display manager
Flatpak	Sandboxed app distribution/runtime
NetworkManager	Network + DNS management
PipeWire / WirePlumber	Audio/video stack
BlueZ	Bluetooth stack
KWallet	Secret Service (auto-unlocked at login)
Waybar	Status bar
SwayNC	Notifications and notification center
SwayOSD	Volume/brightness OSD
Walker / Elephant	Launcher frontend / backend
Matugen, WallRizz	System theming
Pywalfox	Extends system theming into Firefox and Thunderbird
awww	Wallpaper daemon

View Additional Software Suite

Project	Role
KDE	Application suite
Konsole	Terminal ($TERMINAL in config/uwsm/default)
kitty	Alternate terminal; hosts the theme selector's wallpaper grid
Firefox	Web browser
Thunderbird	Mail, calendar, and contacts
LibreOffice	Office suite
Sublime Text	Text editor (hot-reloads its generated color scheme)
qBittorrent	BitTorrent client
Strawberry	Music player
Picard	Music tagger
FileZilla	FTP/SFTP client
Blanket	Ambient sounds
BorgBackup / Vorta	Backup
Nextcloud	File sync client
Vesktop	Discord client
Karere	WhatsApp client
Heroic, Steam	Game store/launcher
RetroArch	Retro game emulator
Chromium	Web app frontend
Hyprshot	Screenshots
Clipse	Clipboard mancager
LazyVim	Neovim config
Starship	Shell prompt
bluetui, wiremix, gazelle-tui	Control-panel TUIs (bluetooth, audio, network)
lazyjournal	Journal/log viewer TUI

Thanks to all of them and thank you for your time.