serpantinum README

The project's README from github.com/ilyamiro/serpantinum. As one markdown file: README.md.

ko-fi
Serpantinum

Previews

Preview 1 Preview 2
Preview 3 Preview 4

[!IMPORTANT] Hey, join our subreddit! Share your setups, ask questions and follow updates at r/serpantinum.

Join r/serpantinum

Installation

[!TIP] Full installation and configuration instructions live at serpantinum.dev.

[!IMPORTANT] Migrating from v1: All previous configuration will be backed up and unused. Configuration of compositor settings such as monitors, keybinds, and autostart is now up to you, as the project migrated from being dotfiles to being a shell.

Arch Linux, Fedora, Void Linux and their derivatives

For Arch-based distributions (including systemd, OpenRC, and other init systems), for Fedora-based distributions such as Nobara and Ultramarine, and for Void Linux (glibc and musl), run the automated installation script. It detects your distribution and uses pacman, dnf or xbps.

Use this installer:

curl -fsSL install.serpantinum.dev | bash

If this doesn't work, use:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/ilyamiro/serpantinum/master/install/install.sh)"

[!NOTE] To update, run the script again and choose "update".


NixOS

See the NixOS installation guide for flake setup, the NixOS and Home Manager modules, and updating.


Audio engine

The equalizer, balance, mono, channel swap, dynamic range modes and the dynamic EQ run on serpantinum-audio, a small PipeWire processor that replaces EasyEffects. The installer and the packages install it, and on the first start after updating, Serpantinum hands your audio over from EasyEffects. See the audio engine guide.


Blue light filter

The blue light filter and its day and night schedule run on serpantinum-gamma, a small Wayland daemon that replaces wl-gammarelay-rs. The installer and the packages install it. Serpantinum starts it the first time a filter is turned on and stops it on exit.


Supported compositors

Hyprland, Niri, Sway and Mango. The installer detects the running compositor and deploys its configuration. On Fedora, Mango is installed from the Terra repository. On Void Linux, Hyprland is installed from the third-party black-hole.dev repository.


Running

To run the shell, launch serpantinumd start

For configuration, see the configuration guide.




Thanks to all contributors


TheRinder2 bizneskind-droid Pigeon78 Eduarduar Spinty-dev MrDexstor coloramamoe Zyxilon gouthamkrishnap Stoltembergg andckadir ArseniiTkachuk MCUxDaredevil MILKv2 pedrolourencosilva Vaspyyy Sergi122 Syrup5845 forteleaf kranks-uga zynx-real




License

Copyright (C) 2026 Illia Miroshnichenko

This project is licensed under the GNU Affero General Public License version 3, or (at your option) any later version. See the LICENSE.md file for the full license text.

serpantinum (ilyamiro/serpantinum)

sway
Searching Database…

What is this?Serpantinum is a shell for Wayland compositors built with Quickshell and QML. It used to be a collection of dotfiles but has now become a standalone shell package you install and update on its own, separately from your compositor config.
Is this a full desktop environment or does it sit on top of my existing window manager?It is not a full desktop environment — it's a shell layer that runs on top of an existing Wayland compositor (Hyprland, Niri, or Sway), while you still own compositor-level config like monitors, keybinds, and autostart.
How do I install and run it?On Arch-based distros, run the project's automated installation script (re-run it later to update). On NixOS, add Serpantinum as a flake input, enable the NixOS module for system prerequisites, and configure it with the Home Manager module; then start the shell with 'serpantinumd start'.
Do I need to configure anything in my compositor myself after installing?Yes — beyond the installer, you have to manually add clipboard listeners and other required services to your compositor's autostart, or the clipboard and equalizer widgets won't work.
Is the install as automated on every distro?Only Arch-based distros get a fully automated installer; on NixOS/Home Manager you must manually integrate the compositor configs yourself, and migrating from the old v1 dotfiles backs up (and discards) your previous setup since compositor-level settings are now entirely your own responsibility.
Which compositors does it actually work with?It targets Hyprland, Niri, and Sway, and ships sample configs, autostart entries, and keybindings for each inside the compositors directory.
How do I actually launch the shell once it's installed?Run 'serpantinumd start' from your terminal or from your compositor's autostart to launch the shell daemon.
Why did the project move away from being plain dotfiles?Packaging it as a shell lets users install and update Serpantinum like regular software with an installer and NixOS modules, while compositor-specific setup like monitors and keybinds stays in the user's own config instead of being bundled dotfiles.
Creator
ilyamiro
Size
120.8 MB
Stars
7.7K
Age
11mo
Commits · 90 Days