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

Installation

[!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 and its derivatives

For Arch-based distributions (including systemd, OpenRC, and other init systems), run the automated installation script.:

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

[!NOTE] To update, when or if you recieve a notification about the new version being available, just run the script again and choose "update"

NixOS

Serpantinum provides flake outputs, a NixOS module for system dependencies, and a Home Manager module for user configuration and service management.

1. Add Flake Input

Add Serpantinum to your flake.nix:

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

  outputs = { self, nixpkgs, serpantinum, ... }: {
    nixosConfigurations.nixos = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      specialArgs = { inherit serpantinum; };
      modules = [
        ./configuration.nix
        serpantinum.nixosModules.default
      ];
    };
  };
}

2. configuration.nix

Enable the NixOS module to configure system prerequisites:

{
  programs.serpantinum.enable = true;
}

If you prefer installing the package directly without the system module:

{ pkgs, serpantinum, ... }:

{
  environment.systemPackages = [
    serpantinum.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];
}

3. Home Manager Configuration

{ serpantinum, ... }:

{
  imports = [
    serpantinum.homeManagerModules.default
  ];

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

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

      general = {
        language = "en";
        weatherUnit = "metric";
        weatherInterval = 30;
      };

      bar = {
        position = "top";
        style = "solid";
        width = 40;
        workspaceCount = 10;
        modules = {
          left = [ "workspaces" ];
          center = [ "time" ];
          right = [ "tray" [ "kb" "wifi" "bt" "vol" "bat" ] ];
        };
      };

      theme = {
        fontFamily = "Adwaita Mono";
        borderRadius = 12;
        matugen = true;
      };

      notifications = {
        dnd = false;
        position = "top right";
        sound = true;
      };
    };
  };
}

4. Updating

Update the flake lockfile and rebuild your system:

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

Note: The automatic installer handles compositor integration on standard distributions. On NixOS / Home Manager, you must manually integrate compositor configs. Sample configs, autostart entries, and keybindings for supported window managers and compositors are available in the compositors directory.

Required autostart

Remember to add clipboard listeners and required services to your compositor's autostart configuration for the clipboard and the equalizer to work properly.

Example on Hyprland:

hl.on("hyprland.start", function()
  hl.exec_cmd("wl-paste --type text --watch cliphist store")
  hl.exec_cmd("wl-paste --type image --watch cliphist store")
  hl.exec_cmd("systemctl --user enable --now easyeffects")
end)

Running

To run the shell, launch serpantinumd start

Credits

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)

Searching Database…

7.3K ·GitHub
Serpantinum
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.
What are similar projects?shell, AgentOS, omarchy-lock-explorer, dots-hyprland, Omarchy-Spotify, omarchy-pods, omarchy-workspace-layout, omarchy
Which topics is it in?qt6, quickshell, desktop-environment, qml, ricing, nixos, arch-linux, tiling-window-manager, widgets, hyprland, linux-desktop, window-manager
Creator
ilyamiro
Size
116.5 MB
Stars
7.3K
Updated
CommitOct 16Releasev2.2.12Oct 16
Age
10mo
Commits · 90 Days