sysc-greet documentation

[HYPRLAND]Your config worked yesterday. Fuck you, update available.│[HYPRLAND]Git bisect is your desktop environment.│[HYPRLAND]Your desktop has more animations than working protocols.│[HYPRLAND]You update once and spend Friday excavating your dotfiles.│[HYPRLAND]Maintainers ship the screenshots. Users debug the release.│[HYPRLAND]Maintainers closed your bug. The rewrite needs a different bug report.│[NIRI]Rust made the compositor memory-safe. Your wrists are on their own.│[NIRI]Infinite workspace, finite chance of finding the window you lost.│[NIRI]Horizontal scrolling turned into a fucking worldview.│[NIRI]Scrollable tiling makes fixed workspaces feel broken.│[NIRI]The rare new compositor whose big idea survives a full workday.│[NIRI]Wayland found a good reason to scroll sideways.│[GNOME]Developers removed the feature and published a manifesto about your mistake.│[GNOME]The settings panel has fewer options than the developers have opinions.│[GNOME]Your workflow failed ideological review.│[GNOME]Developers removed your button and called the empty space intentional.│[GNOME]Extensions let volunteers restore what maintainers removed on principle.│[GNOME]Your right-click menu died for somebody's design system.│[HYPRLAND]Your config worked yesterday. Fuck you, update available.│[HYPRLAND]Git bisect is your desktop environment.│[HYPRLAND]Your desktop has more animations than working protocols.│[HYPRLAND]You update once and spend Friday excavating your dotfiles.│[HYPRLAND]Maintainers ship the screenshots. Users debug the release.│[HYPRLAND]Maintainers closed your bug. The rewrite needs a different bug report.│[NIRI]Rust made the compositor memory-safe. Your wrists are on their own.│[NIRI]Infinite workspace, finite chance of finding the window you lost.│[NIRI]Horizontal scrolling turned into a fucking worldview.│[NIRI]Scrollable tiling makes fixed workspaces feel broken.│[NIRI]The rare new compositor whose big idea survives a full workday.│[NIRI]Wayland found a good reason to scroll sideways.│[GNOME]Developers removed the feature and published a manifesto about your mistake.│[GNOME]The settings panel has fewer options than the developers have opinions.│[GNOME]Your workflow failed ideological review.│[GNOME]Developers removed your button and called the empty space intentional.│[GNOME]Extensions let volunteers restore what maintainers removed on principle.│[GNOME]Your right-click menu died for somebody's design system.│

Features

Multiple Themes: Dracula, Gruvbox, Material, Nord, Tokyo Night, Catppuccin, Solarized, Monochrome, TransIsHardJob, Eldritch, RAMA, Dark, Ayu, Amber, Blue, Purple, Green, Orange, Coral, Cyan, Eldritch-Abyss, Kanagawa, Noctalia, Pink, Red, Rose-Pine, Void (plus custom themes)
Background Effects: Fire, ASCII Rain, Matrix, Fireworks, Aquarium, Sonar, Cracktro, Plasma, AK-47, Australian SLR, Higgs Field, plus rotating statues and fighters
ANSI Headers: Configurable per-session art with opt-in embedded SGR colors
ASCII Effects: Typewriter, Print, Beams, and Pour effects for session text
Secondary Displays: Selected effects mirror across supported compositor outputs; configured screensavers use read-only Kitty windows
Border Styles: Classic, Modern, Minimal, ASCII-1, ASCII-2, NFO 01–03, Braille Hairline, Sextant Bevel, shimmer, and palette cycling
Screensaver: Configurable idle timeout with ASCII art cycling
Video Wallpapers: gSlapper support across monitors
Security Features: Failed attempt counter with account lockout warnings, optional username caching

Installation

Quick Install Script

One-line install for most systems:

curl -fsSL https://raw.githubusercontent.com/Nomadcxx/sysc-greet/master/install.sh | sudo bash

Manual Build

The installer lets you choose your compositor and handles all configuration:

git clone https://github.com/Nomadcxx/sysc-greet
cd sysc-greet
go run ./cmd/installer/

Arch Linux (AUR)

sysc-greet provides five AUR packages for different greeter compositors:

# niri (default)
yay -S sysc-greet

# Cagebreak variant
yay -S sysc-greet-cagebreak

# Sway variant
yay -S sysc-greet-sway

# Mango variant
yay -S sysc-greet-mango

# Hyprland 0.55+ Lua variant
yay -S sysc-greet-hyprland

The packages conflict with each other, so install exactly one. The Hyprland package requires Hyprland 0.55 or newer. sysc-greet-cagebreak also installs socat so it can quit Cagebreak after login.

Pre-built Packages (.deb / .rpm)

Download from GitHub Releases:

Debian/Ubuntu:

wget https://github.com/Nomadcxx/sysc-greet/releases/download/v1.3.0/sysc-greet_1.3.0_amd64.deb
sudo apt install ./sysc-greet_1.3.0_amd64.deb

Fedora:

wget https://github.com/Nomadcxx/sysc-greet/releases/download/v1.3.0/sysc-greet-1.3.0-1.x86_64.rpm
sudo dnf install ./sysc-greet-1.3.0-1.x86_64.rpm

Package configs use conservative syntax for stable distro compatibility. For bleeding-edge compositor features, use the install script or AUR instead.

NixOS (Flake)

Add sysc-greet to your NixOS configuration using the flake:

flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    sysc-greet = {
      url = "github:Nomadcxx/sysc-greet";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, sysc-greet, ... }: {
    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        sysc-greet.nixosModules.default
      ];
    };
  };
}

configuration.nix:

{
  services.sysc-greet = {
    enable = true;
    compositor = "niri";  # or "cagebreak", "sway", "mango", "hyprland" (0.55+)
  };

  # Optional: Set initial session for auto-login
  services.sysc-greet.settings.initial_session = {
    command = "Hyprland";
    user = "your-username";
  };
}

By default, the NixOS module does not install niri, cagebreak, hyprland, sway, or mango. Install your chosen backend yourself, or set niriPackage, cagebreakPackage, hyprlandPackage, swayPackage, or mangoPackage if you want the module to install and use a specific package. Mango is not in nixpkgs; mangoPackage must come from your own flake. If your compositor is managed elsewhere, set compositorCommand to the exact command greetd should run.

Then rebuild your system:

sudo nixos-rebuild switch --flake .#your-hostname

Advanced: Manual Build from Source

Requirements:

Go 1.25+
greetd
Wayland compositor: niri (default), cagebreak, sway, mango, or Hyprland 0.55+ (sysc-compositor: experimental)
socat (cagebreak only — quits the compositor after login)
kitty (terminal)
gSlapper (wallpaper daemon)
swww (legacy wallpaper daemon, optional fallback)

Build and install:

git clone https://github.com/Nomadcxx/sysc-greet
cd sysc-greet
go build -o sysc-greet ./cmd/sysc-greet/
sudo install -Dm755 sysc-greet /usr/local/bin/sysc-greet

Install assets:

sudo mkdir -p /usr/share/sysc-greet/{ascii_configs,fonts,wallpapers}
sudo cp -r ascii_configs/* /usr/share/sysc-greet/ascii_configs/
sudo cp -r fonts/* /usr/share/sysc-greet/fonts/
sudo cp -r wallpapers/* /usr/share/sysc-greet/wallpapers/
sudo cp config/kitty-greeter.conf /etc/greetd/kitty.conf

Configure greetd (/etc/greetd/config.toml):

Choose your compositor and update the command below:

[terminal]
vt = 1

[default_session]
# Pick one:
command = "niri -c /etc/greetd/niri-greeter-config.kdl"
# command = "cagebreak -e -c /etc/greetd/cagebreak-greeter-config"
# command = "sway --unsupported-gpu -c /etc/greetd/sway-greeter-config"
# command = "mango -c /etc/greetd/mango-greeter-config.conf -s /etc/greetd/mango-greeter-session.sh"
# command = "start-hyprland -- --config /etc/greetd/hyprland-greeter-config.lua"
user = "greeter"

Create compositor config:

Copy the appropriate config file to /etc/greetd/:

# For niri:
sudo cp config/niri-greeter-config.kdl /etc/greetd/

# For cagebreak:
sudo cp config/cagebreak-greeter-config /etc/greetd/

# For sway:
sudo cp config/sway-greeter-config /etc/greetd/

# For mango:
sudo cp config/mango-greeter-config.conf /etc/greetd/
sudo install -m755 config/mango-greeter-session.sh /etc/greetd/

# For Hyprland 0.55+:
sudo cp config/hyprland-greeter-config.lua /etc/greetd/

Create greeter user:

sudo useradd -M -d /var/lib/greeter -G video,render,input -s /usr/bin/nologin greeter
sudo mkdir -p /var/cache/sysc-greet /var/lib/greeter/Pictures/wallpapers \
    /var/lib/greeter/.cache /var/lib/greeter/.config /var/lib/greeter/.local/state
sudo chown -R greeter:greeter /var/cache/sysc-greet /var/lib/greeter
sudo chmod 755 /var/lib/greeter

Enable service:

sudo systemctl enable greetd.service

Usage

Key Bindings

F1 - Settings menu (themes, borders, backgrounds)
F2 - Session selection
F3 - Release notes
F4 - Power menu (shutdown/reboot)
Page Up/Down - Cycle ASCII variants
Tab - Navigate fields
Enter - Submit/Continue
Esc - Cancel/Return to previous screen

Test Mode

Test the greeter without locking your session:

sysc-greet --test

# Test in fullscreen (recommended for accurate preview)
kitty --start-as=fullscreen sysc-greet --test

Additional Options

sysc-greet --theme dracula          # Start with specific theme
sysc-greet --screensaver            # Enable screensaver in test mode
sysc-greet --remember-username      # Cache username across sessions
sysc-greet --debug                  # Enable debug logging
sysc-greet --version                # Show version information

Configuration

sysc-greet stores user preferences in /var/cache/sysc-greet/. The following settings are cached:

Theme - Selected color theme
Background - Selected background effect or video wallpaper
Border Style - Selected border style
Session - Last selected session
Username - Last entered username (if --remember-username enabled)
ASCII Index - Last selected ASCII variant

Themes

sysc-greet includes multiple color themes:

Theme	Primary Color	Description
Dracula	#bd93f9	Dark purple-blue theme
Gruvbox	#fe8019	Warm dark theme
Material	#80cbc4	Material Design dark theme
Nord	#81a1c1	Arctic blue-toned dark theme
Tokyo Night	#7aa2f7	Modern dark theme
Catppuccin	#cba6f7	Soft pastel dark theme
Solarized	#268bd2	Solarized dark theme
Monochrome	#ffffff	Black and white minimal theme
TransIsHardJob	#5BCEFA	Transgender flag colors
Eldritch	#37f499	Purple and green theme
RAMA	#ef233c	RAMA keyboard aesthetics
Dark	#ffffff	True black and white minimal theme
Ayu	#e6b450	Dark theme with a gold primary and green and blue accents
Amber	#ffc107	Brown-black with amber accents
Blue	#42a5f5	Blue-grey with a blue primary
Purple	#d0bcff	Near-black with Material violet
Green	#4caf50	Green-black with a green primary
Orange	#ff6d00	Brown-black with an orange primary
Coral	#ffb4ab	Brown-black with a soft coral primary
Cyan	#00bcd4	Dark slate with a cyan primary
Eldritch-Abyss	#2dcc82	Deep indigo with green, teal, and violet accents
Kanagawa	#76946a	Ink-wash dark theme with pine and wave blue accents
Noctalia	#fff59b	Midnight blue with pale yellow, periwinkle, and mint accents
Pink	#e91e63	Brown-black with a magenta-pink primary
Red	#f44336	Brown-black with a red primary
Rose-Pine	#ebbcba	Warm rose and foam accents on a plum base
Void	#ffffff	True black with a white primary

Fifteen themes ship as TOML files in /usr/share/sysc-greet/themes/; the rest are built in. Custom themes can be added in the same directory or in ~/.config/sysc-greet/themes/. See Themes Configuration for details.

Background Effects

sysc-greet includes these background effects:

Fire
Matrix
ASCII Rain
Fireworks
Aquarium
Sonar
Cracktro
Plasma
AK-47
Australian SLR (L2A1 SAR)
Higgs Field
Rotating statues, landmarks, and fighter aircraft

Wallpapers

sysc-greet supports two types of wallpapers:

Themed Wallpapers - Static images that match selected theme (stored in /usr/share/sysc-greet/wallpapers/)
Video Wallpapers - Video backgrounds managed by gSlapper (stored in /var/lib/greeter/Pictures/wallpapers/)

For detailed configuration, see Wallpapers Feature.

ASCII Art

Each session can have custom ASCII art with multiple variants. Press Page Up/Down at the greeter to cycle through variants.

ASCII art configurations are stored in /usr/share/sysc-greet/ascii_configs/. Each session has a .conf file containing:

name - Display name for the session
ascii_1, ascii_2, etc. - Multiple ASCII art variants
color - Optional hex color for plain art
ansi_style - true for art with embedded ANSI colors
roasts - Custom roast messages separated by │ character

For more details, see ASCII Art Feature.

Screensaver

The screensaver activates after a configurable idle timeout and displays:

Current time and date
ASCII art cycling
Optional print animation effect

On secondary outputs it mirrors the configured art and clock in read-only fullscreen Kitty windows. It takes precedence over effects and wallpapers, including GSlapper video. Input in any saver window wakes the primary greeter and closes the other saver windows.

Screensaver configuration is in /usr/share/sysc-greet/ascii_configs/screensaver.conf.

Compositor Setup

sysc-greet runs its greeter under Niri, Cagebreak, Sway, Mango, or Hyprland 0.55+. Set SYSC_COMPOSITOR=hyprland to opt into Hyprland. Experimental sysc-compositor builds are detected and run with the Niri config. Check startup, login, and quit on the target machine before enabling greetd. For setup instructions, see:

Niri Setup — default
Cagebreak Setup
Sway Setup
Mango Setup — Arch, Debian 13, Ubuntu 26.04, Fedora 43/44
Hyprland Setup — explicit opt-in, Lua config, version 0.55+

Development

Building

make build

Testing

make test

Running in Test Mode

./sysc-greet --test --debug

For development details, see Development Guide.

Troubleshooting

Greeter won't start:

sudo systemctl status greetd
journalctl -u greetd -n 50

Check gSlapper status:

# Check if gSlapper is running
ps aux | grep gslapper

# View gSlapper debug log
cat /tmp/sysc-greet-wallpaper.log

Debug logging:

# Run with debug flag
sysc-greet --debug

# View debug log
cat /tmp/sysc-greet-debug.log

For more troubleshooting, see Troubleshooting Guide.

If you like ASCII animations, CLI and TUI terminal aesthetics check out these projects:

sysc-Go - Terminal animation library for Go
sysc-walls - Terminal-based screensaver for Wayland/X11
sysclet - ANSI headers from TheDraw fonts, written straight into sysc-greet profiles
gSlapper - Video wallpaper manager for Wayland

Acknowledgments

tuigreet by apognu - Original inspiration and base
Bubble Tea by Charm - TUI framework
Lipgloss by Charm - Terminal styling
greetd by kennylevinsen - Login manager

License

sysc-greet's own source code is GPL-3.0-only.

See THIRD_PARTY_NOTICES.md for notices covering third-party code and model assets supplied through sysc-Go.