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.4K ·GitHub
Serpantinum
Что это такое?Serpantinum — оболочка для композиторов Wayland, построенная на Quickshell и QML. Раньше это была коллекция дотфайлов, а теперь стала самостоятельным пакетом оболочки, который устанавливается и обновляется отдельно, независимо от конфигурации вашего композитора.
Это полноценная среда рабочего стола или надстройка над моим текущим оконным менеджером?Это не полноценная среда рабочего стола — это слой оболочки, работающий поверх существующего композитора Wayland (Hyprland, Niri или Sway), при этом конфигурация уровня композитора, например мониторы, клавиатурные сочетания и автозапуск, остаётся за вами.
Как его установить и запустить?На дистрибутивах на базе Arch запустите автоматический скрипт установки проекта (позже перезапускайте его для обновления). На NixOS добавьте Serpantinum как flake-вход, включите модуль NixOS для системных предпосылок и настройте его через модуль Home Manager; затем запустите оболочку командой 'serpantinumd start'.
Нужно ли после установки самому что-то настроить в композиторе?Да — помимо установщика, придётся вручную добавить слушателей буфера обмена и другие нужные службы в автозапуск вашего композитора, иначе виджеты буфера обмена и эквалайзера не будут работать.
Установка одинаково автоматизирована на всех дистрибутивах?Полностью автоматический установщик есть только у дистрибутивов на базе Arch; на NixOS/Home Manager интеграцию конфигураций композитора придётся выполнить вручную, а миграция со старых дотфайлов v1 создаёт резервную копию (и отбрасывает) вашу прежнюю настройку, поскольку настройки уровня композитора теперь полностью ваша ответственность.
С какими композиторами он реально работает?Он нацелен на Hyprland, Niri и Sway и поставляет примеры конфигураций, записи автозапуска и привязки клавиш для каждого в каталоге compositors.
Как на самом деле запустить оболочку после установки?Запустите 'serpantinumd start' из вашего терминала или из автозапуска вашего композитора, чтобы стартовать демон оболочки.
Почему проект отказался от формата простых дотфайлов?Упаковка в виде оболочки позволяет пользователям устанавливать и обновлять Serpantinum как обычное ПО с установщиком и модулями NixOS, при этом специфичная для композитора настройка вроде мониторов и привязок клавиш остаётся в конфигурации самого пользователя, а не в комплектных дотфайлах.
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, ricing, nixos, qml, arch-linux, tiling-window-manager, widgets, hyprland, linux-desktop, window-manager
Creator
ilyamiro
Size
117.6 MB
Stars
7.4K
Updated
CommitOct 17Releasev2.2.12Oct 16
Age
10mo
Commits · 90 Days