Serpantinum: A Configurable Desktop Shell for Wayland Compositors

What Serpantinum Is and the Problem It Solves

Wayland compositors such as Hyprland handle window management but do not ship a complete desktop shell on their own. Users typically assemble a shell from separate tools: a status bar, a workspace indicator, a system tray, a clipboard manager, and a notification daemon. Serpantinum bundles these into one QML application that integrates with the compositor over Wayland protocols.

The project targets Linux users on Arch-based distributions and NixOS who run Hyprland or another supported Wayland compositor and want a shell that can be configured through a structured settings file rather than assembled from disparate packages. The README notes that version 2 shifted the project's scope from a dotfiles bundle to a standalone shell, meaning compositor-level settings such as keybindings and autostart entries are no longer managed by Serpantinum and must be configured separately.

The shell is written in QML and is licensed under AGPL-3.0.

Architecture: QML, the Bar, and Compositor Integration

Serpantinum is implemented in QML, the declarative UI language used by the Qt framework. The main daemon is launched with the `serpantinumd start` command. The repository layout shows source code in src/, NixOS module definitions in nix/, compositor integration examples in compositors/, and default configuration in config/.

The shell provides a configurable status bar. The bar position (top or bottom) and style (solid or other variants) are set in the configuration. Bar width and workspace count are also configurable. Modules are assigned to left, center, and right positions. The README's Home Manager example shows a bar with workspaces on the left, time in the center, and a tray with keyboard and Wi-Fi indicators on the right.

For clipboard functionality, the shell relies on wl-clipboard services running as autostart entries. The README shows a Hyprland example that starts wl-paste listeners on compositor startup, which feed cliphist with text and image clipboard data. The equalizer feature requires easyeffects as a user systemd service. These services are not managed by the shell itself and must be added to the compositor's autostart configuration manually.

Installing on Arch Linux and Its Derivatives

For Arch-based distributions, the project provides an automated installation script. Fetch and run it with:

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

The README notes that the same script handles updates: when a notification about a new version arrives, run the script again and choose the update option.

The script supports distributions with systemd, OpenRC, and other init systems. After installation, start the shell with:

serpantinumd start

This applies after the compositor is running and the required autostart services are configured.

Installing on NixOS with Flakes and Home Manager

NixOS users integrate Serpantinum through its flake outputs. The installation involves three steps: adding the flake input, enabling the NixOS module, and configuring the Home Manager module.

Add the flake input to flake.nix:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    serpantinum.url = "github:ilyamiro/serpantinum";
  };
}

Enable the NixOS module in configuration.nix:

{
  programs.serpantinum.enable = true;
}

Configure the Home Manager module with your settings:

{ serpantinum, ... }:
{
  imports = [
    serpantinum.homeManagerModules.default
  ];

  programs.serpantinum = {
    enable = true;
    systemd.enable = true;

    settings = {
      wallpaperDir = "/home/username/Pictures/Wallpapers";
    };
  };
}

Update the flake lockfile and rebuild with:

nix flake update serpantinum
sudo nixos-rebuild switch --flake .

The README notes that on NixOS the automatic installer does not handle compositor integration. Sample configurations for autostart, keybindings, and monitor setup for supported compositors are available in the compositors/ directory of the repository.

Limitations and Cases Where It Is the Wrong Tool

Serpantinum does not manage compositor settings. After migrating from version 1, the README notes that all previous configuration related to monitors, keybindings, and autostart is backed up and unused. Users must configure those settings directly in their compositor.

The clipboard and equalizer features depend on external services (wl-clipboard and easyeffects) that must be added to autostart by the user. If those services are not running, those shell features do not work.

The project has no GitHub releases. Versioning is tracked in version.txt at the repository root. There is no binary distribution outside of the install script and the NixOS flake.

The AGPL-3.0 license requires that any modified version distributed over a network also provide its source code. This is a meaningful constraint for any commercial product built on or incorporating Serpantinum.

Comparison with Standalone Bar Tools

The most common alternative approach on Hyprland is to combine separate tools: a standalone bar such as Waybar or Yambar, a clipboard manager such as cliphist with a wl-paste frontend, and a notification daemon such as mako or dunst. This gives more flexibility, since each component can be swapped independently, but requires assembling and maintaining separate configuration files for each tool.

Serpantinum integrates these functions into a single shell application with one configuration format, which reduces the number of configuration files to maintain. The trade-off is that the shell's component choices are fixed: users who prefer a specific bar or notification daemon cannot mix and match at that level.

The README does not document integration with GNOME Shell or KDE Plasma. Serpantinum targets raw compositor setups, not desktop environments that already ship their own shell.

Maintenance and License

The repository is not archived. The last push was on 2026-09-27. A CHANGELOG.md exists in the repository root, tracking changes across versions. The flake.lock file is present, indicating that NixOS inputs are pinned.

The project is licensed under AGPL-3.0. The license text is in LICENSE.md. AGPL-3.0 is a strong copyleft license: any derivative work that is made available over a network must also provide its source code under the same license. For personal desktop use, this has no practical effect. For developers building commercial desktop products that incorporate or modify Serpantinum, this requires legal review.

Editorial conclusion

Serpantinum fits Wayland users on Arch-based distributions or NixOS who want a configurable shell with a status bar and workspace switcher without assembling multiple standalone bar and clipboard tools from scratch. It is not a drop-in replacement for GNOME Shell or KDE Plasma and does not manage compositor settings such as keybindings or monitor layout; those remain the user's responsibility after migrating from version 1. The AGPL-3.0 license requires source disclosure for any network-facing deployment built on it, which is a meaningful constraint for commercial desktop products. The last push was on 2026-09-27.

Frequently asked questions

Official sources

1. ilyamiro/serpantinum on GitHub
2. Issues
3. License: AGPL-3.0
4. README