Desktop environment

The Keystone desktop module provides a complete Wayland desktop built on the Hyprland tiling compositor. It includes session management via UWSM, audio through PipeWire, login with greetd, a comprehensive keybinding system, screen recording with GPU-accelerated encoding, night light filtering, and monitor management. The desktop module automatically enables the terminal module, so all terminal tools are available within the graphical environment.

Enabling the module

The desktop environment is enabled per-user through the keystone.os.users option. The system-level NixOS desktop module must also be imported in the flake configuration.

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
    keystone.url = "github:ncrmro/keystone";
    home-manager.url = "github:nix-community/home-manager/release-25.05";
  };

  outputs = { nixpkgs, keystone, home-manager, ... }: {
    nixosConfigurations.workstation = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        home-manager.nixosModules.home-manager
        keystone.nixosModules.operating-system
        keystone.nixosModules.desktop
        {
          keystone.os = {
            enable = true;
            storage = {
              type = "zfs";
              devices = [ "/dev/disk/by-id/nvme-WD_BLACK_SN850X_2TB" ];
            };
            users.alice = {
              fullName = "Alice Smith";
              email = "alice@example.com";
              extraGroups = [ "wheel" "networkmanager" ];
              initialPassword = "changeme";
              terminal.enable = true;
              desktop = {
                enable = true;
                hyprland.modifierKey = "SUPER";
              };
            };
          };
        }
      ];
    };
  };
}

Hyprland compositor

Hyprland is a dynamic tiling Wayland compositor. Keystone uses the official Hyprland flake for the latest features and integrates it with UWSM (Universal Wayland Session Manager) for proper session lifecycle management.

Session management

Sessions are managed through UWSM, which handles:

Proper systemd user session setup for the Wayland compositor.
D-Bus activation and XDG portal initialization.
Clean session teardown on logout.

The greetd login manager starts the Hyprland session via uwsm start -F Hyprland. Applications that require the Wayland session should be launched through uwsm app -- to ensure they inherit the correct environment.

Default applications

The following default applications are configured:

Keybinding system

The keybinding system is designed for a fully keyboard-driven workflow with consistent patterns across all tools.

Modifier key strategy

Keystone uses a layered modifier approach to avoid conflicts between the compositor, terminal multiplexer, and applications:

By default, altwin:swap_alt_win is enabled in the keyboard options. This swaps the physical Alt and Super keys so that the physical Alt key (in the ergonomic thumb position) sends Super keycodes. The result is that frequent window management operations are accessible from the natural thumb resting position. The physical Super key then sends Alt keycodes, which provides browser back/forward navigation via Alt+Left/Right (sent by pressing physical Super+Arrow).

Caps Lock is remapped to Control by default (ctrl:nocaps). This places Ctrl in a more ergonomic position for terminal and editor usage. The remapping can be disabled by setting capslockAsControl = false, which instead maps Caps Lock to the Compose key.

Window management

Focus navigation

Window movement

Workspace navigation

Utilities and menus

Hardware keys

Hardware portability

The keybinding system is designed to work consistently across different keyboard hardware without requiring per-device Nix configuration. The OS-level key swap (altwin:swap_alt_win) ensures that any keyboard -- whether a Framework laptop keyboard, a UHK split keyboard with custom layers, or a standard desktop keyboard -- sends consistent keycodes to Hyprland.

Ghostty integration

The Ghostty terminal emulator is configured to delegate all multiplexing to Zellij. Ghostty's built-in tab and split management keybindings are unbound to prevent conflicts:

Ctrl+PageUp/Down and Ctrl+Tab are unbound (Zellij handles tab navigation).
Ctrl+Shift+O and directional splits are unbound (Zellij handles pane management).
Ghostty retains its own tab shortcuts on Ctrl+Shift+W/E/R/C for the rare case where Ghostty-level tabs are needed outside of Zellij.

PipeWire audio

PipeWire provides the audio stack with compatibility layers for ALSA, PulseAudio, and JACK. It is enabled by default when the desktop module is active.

The configuration includes:

rtkit: Real-time scheduling for low-latency audio.
PulseAudio: Disabled in favor of PipeWire's PulseAudio compatibility layer.
ALSA, Pulse, and JACK: All PipeWire compatibility backends enabled.

Audio devices can be managed through pavucontrol (PulseAudio Volume Control), which is included in the desktop system packages.

greetd login manager

greetd is a minimal, daemon-based login manager. Keystone configures it with auto-login to the Hyprland session via UWSM. The PAM session is registered as a Wayland session with class user, which ensures that loginctl lock-session functions correctly for the lock screen.

Menu system

The Keystone menu system is accessible via Mod+Escape or the power button. It provides a hierarchical launcher with the following categories:

Apps: Application launcher.
Capture: Screenshot and screen recording controls.
Toggle: Night light, idle inhibition, and system feature toggles.
Style: Theme switching.
Setup: Monitor configuration and system settings.
System: Lock, suspend, restart, and shutdown.
Learn: Keybindings reference and documentation.

The menu can be invoked with a category argument to navigate directly to a specific submenu (for example, keystone-menu system).

Screen recording

Keystone provides built-in screen recording through gpu-screen-recorder, using GPU-accelerated encoding for minimal performance impact.

Starting and stopping

There are three ways to control screen recording:

Menu: Press Mod+Escape, navigate to "Capture", and select "Screenrecord".
Waybar indicator: A red indicator appears in the center of the status bar while recording. Clicking it stops the recording.
Command line: Use the keystone-screenrecord command.

# Start recording (video only)
keystone-screenrecord

# Record with desktop audio
keystone-screenrecord --with-desktop-audio

# Record with microphone
keystone-screenrecord --with-microphone-audio

# Record with both audio sources
keystone-screenrecord --with-desktop-audio --with-microphone-audio

# Stop an active recording
keystone-screenrecord --stop

Running keystone-screenrecord while a recording is already active will stop the current recording (toggle behavior).

Audio configuration

Audio capture is opt-in. Without any flags, recordings contain video only.

Desktop audio uses the PipeWire default_output device, and microphone audio uses the PipeWire default_input device. When both sources are active, they are mixed into a single synchronized AAC audio track at 128 kbps.

Output files

Recordings are saved as MP4 files with GPU-accelerated H.264 encoding at 60 FPS and native monitor resolution. The output location is determined in the following order:

$KEYSTONE_SCREENRECORD_DIR (if set).
$XDG_VIDEOS_DIR (typically ~/Videos).
~/Videos as a fallback.

Files are named screenrecording-YYYY-MM-DD_HH-MM-SS.mp4 and sort chronologically in file browsers.

To save recordings to a project-specific directory:

export KEYSTONE_SCREENRECORD_DIR=~/Projects/my-project/recordings
mkdir -p "$KEYSTONE_SCREENRECORD_DIR"
keystone-screenrecord

Technical details

The recording engine (gpu-screen-recorder) supports NVIDIA NVENC, Intel Quick Sync, and AMD VCE hardware encoders.

Night light

Blue light filtering is provided by Hyprsunset. The filter can be toggled via Mod+Ctrl+N or through the "Toggle" category in the Keystone menu. The menu also allows configuration of the schedule (start and end times) and intensity (color temperature).

Monitor management

The desktop module includes monitor management capabilities for dynamic display configuration. The menu system provides a "Monitors" section under "Setup" that lists connected displays and offers options for mirroring, resolution presets, and multi-monitor arrangement. An autoMirror configuration option, when enabled, automatically mirrors the primary display to any newly connected external monitor.

Screen locking

Screen locking is handled by Hyprlock, which integrates with the system PAM stack. The lock screen supports:

Fingerprint authentication.
Time display and themed background.
Visual feedback for authentication failures.
Automatic activation via Hypridle after a configurable idle period.

Idle inhibition can be toggled with Mod+Ctrl+I to prevent automatic locking during presentations or long-running tasks. D-Bus inhibition requests from applications (such as browsers playing media) are ignored by default to ensure the screen locks when the user is genuinely idle.

Bluetooth and networking

The desktop module enables Bluetooth support with Blueman for device management, and NetworkManager with systemd-resolved for network configuration. These services are appropriate for laptops, portable machines, and thin client setups.

The resolv.conf is configured as a direct symlink to support Tailscale MagicDNS with systemd-resolved.

Fonts and theming

The following font families are installed:

Noto Sans and Noto Color Emoji.
JetBrains Mono Nerd Font.
Caskaydia Mono Nerd Font.

The theming system supports runtime switching between multiple themes (such as Tokyo Night, Catppuccin, and Nord). A theme switch updates the window manager, status bar, terminal emulator, text editor, application launcher, notification daemon, wallpaper, and GTK settings consistently. The selected theme persists across reboots.

System packages

The desktop module installs the following system-level packages:

NixOS module options

The NixOS-level desktop module (keystone.desktop) exposes the following options:

Per-user Hyprland options are configured through keystone.os.users.<name>.desktop: