Installation

This guide covers installation methods for sysc-greet across different Linux distributions.

Quick Install Script

One-line install for most systems:

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

The interactive installer will prompt you to:

Choose your greeter backend (niri default, cagebreak, sway, or hyprland deprecated)
Configure backend settings
Install dependencies automatically

Hyprland greeter support ends in ~3 months. Migrate to cagebreak or niri.

Manual Build

Prerequisites

Go 1.25+
greetd
Wayland backend: niri (default), cagebreak, sway, or hyprland (deprecated)
kitty (terminal emulator)
gSlapper (wallpaper daemon)
swww (legacy wallpaper daemon, optional fallback)

Build Steps

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

Run Installer

The installer handles compositor configuration automatically:

go run ./cmd/installer/

Arch Linux (AUR)

sysc-greet provides four AUR packages, one per greeter backend:

# niri (default)
yay -S sysc-greet

# Cagebreak variant (the Hyprland replacement)
yay -S sysc-greet-cagebreak

# Sway variant
yay -S sysc-greet-sway

# Hyprland variant (deprecated, replaced by cagebreak)
yay -S sysc-greet-hyprland

The packages conflict with each other — install exactly one. Each pulls in its compositor as a dependency; sysc-greet-cagebreak also pulls in socat, which is required to quit the compositor after login.

Pre-built Packages

Download pre-built packages from GitHub Releases:

Debian/Ubuntu (.deb)

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

The package will:

Install sysc-greet to /usr/local/bin/
Install configs to /usr/share/sysc-greet/
Detect your compositor and configure greetd
Enable the greetd service

Note: Package configs use conservative syntax compatible with stable distribution versions. For bleeding-edge compositor features, use the install script or AUR instead.

Fedora (.rpm)

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

After installation, reboot your system to see sysc-greet.

The releases page also carries cagebreak .deb/.rpm packages (Debian 13, Ubuntu 24.04/25.x, Fedora 42) since no distro packages exist — see Cagebreak Setup.

Switching Compositors

The package auto-detects your compositor during installation. If you have multiple compositors installed or want to switch to a different one, edit /etc/greetd/config.toml:

sudo nano /etc/greetd/config.toml

Change the command line to your preferred compositor:

Niri:

[default_session]
command = "niri -c /etc/greetd/niri-greeter-config.kdl"
user = "greeter"

Cagebreak:

[default_session]
command = "cagebreak -e -c /etc/greetd/cagebreak-greeter-config"
user = "greeter"

-e enables cagebreak's IPC socket, which the greeter config uses to quit the compositor after login — socat must be installed. See Cagebreak Setup.

Sway:

[default_session]
command = "sway -c /etc/greetd/sway-greeter-config"
user = "greeter"

Hyprland (deprecated):

[default_session]
command = "Hyprland -c /etc/greetd/hyprland-greeter-config.conf"
user = "greeter"

All compositor configs are installed at /etc/greetd/. Save the file and reboot to apply the change.

NixOS (Flake)

Add to 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
      ];
    };
  };
}

Add to configuration.nix

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

  # 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, or sway. Install your chosen backend yourself, or set niriPackage, cagebreakPackage, hyprlandPackage, or swayPackage if you want the module to install and use a specific package. If your compositor is managed elsewhere, set compositorCommand to the exact command greetd should run.

Rebuild System

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

Post-Installation Setup

Configure greetd

Edit /etc/greetd/config.toml:

[terminal]
vt = 1

[default_session]
# Choose your compositor:
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 = "start-hyprland -- -c /etc/greetd/hyprland-greeter-config.conf"
user = "greeter"

Install Compositor Config

Copy the appropriate config to /etc/greetd/:

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

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

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

# hyprland (deprecated)
sudo cp config/hyprland-greeter-config.conf /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

Verification

After installation, test the greeter:

sysc-greet --test

For fullscreen testing:

kitty --start-as=fullscreen sysc-greet --test

Uninstall

Quick Install Script / Manual Build

Re-run the installer and select Uninstall sysc-greet:

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

The uninstaller removes:

/usr/local/bin/sysc-greet — binary
/usr/share/sysc-greet/ — ASCII configs, wallpapers, data files
/etc/greetd/kitty.conf and compositor config files
/var/cache/sysc-greet/ — saved preferences (optional step)

The greeter user and /var/lib/greeter/ are intentionally preserved.

Pre-built Packages

Debian/Ubuntu:

sudo apt remove sysc-greet

Fedora:

sudo dnf remove sysc-greet

Arch Linux (AUR)

yay -R sysc-greet
# replace with sysc-greet-cagebreak, sysc-greet-sway, or sysc-greet-hyprland if applicable

NixOS

Remove the sysc-greet module from configuration.nix and rebuild:

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

After Uninstalling

To stop greetd from failing on next boot:

sudo systemctl disable greetd.service

Troubleshooting

IPC Client Error

If you see FATAL: Failed to create IPC client, check that:

You are not setting GREETD_SOCK environment variable manually
greetd is actually running and has created the socket
You are running sysc-greet through greetd (not directly in terminal)

Compositor Not Starting

Check compositor logs:

journalctl -u greetd -n 50

Greeter Not Appearing

Verify:

greetd service is enabled and running: systemctl status greetd
compositor config exists in /etc/greetd/
greeter user has proper permissions

For more help, see Troubleshooting Guide.

On this page