Quick Start

Installation

Install Stasis from your package manager when available, or build it from source.

Arch Linux

yay -S stasis
# or track git builds
yay -S stasis-git

Nix / NixOS

nix build 'github:saltnpepper97/stasis#stasis'

From Source

Runtime dependencies include Wayland, D-Bus, and pulseaudio or pipewire-pulse for media detection through pactl.

git clone https://github.com/saltnpepper97/stasis
cd stasis
cargo build --release --locked
sudo install -Dm755 target/release/stasis /usr/local/bin/stasis
sudo install -Dm644 assets/stasis.png /usr/local/share/icons/hicolor/256x256/apps/stasis.png

Session Setup

Start your compositor inside a real D-Bus session when using enable_dbus_inhibit or other session-bus features.

Use your compositor or distribution's recommended launcher, such as niri-session, dbus-run-session, or another session wrapper that provides DBUS_SESSION_BUS_ADDRESS to user services.

Screen Lockers

Stasis uses the configured locker process as a compatibility fallback. If the locker or compositor publishes login1 LockedHint=true, that system state automatically becomes authoritative until the real unlock.

No locker mode is required. Traditional foreground lockers keep working through process tracking. Service-backed lockers such as Veila work through LockedHint, even when their command-line client exits after the secure surface is ready.

A locker that forks into the background without publishing LockedHint exposes no reliable unlock state. Run that locker in the foreground. Do not use a loginctl lock-session wrapper: login1 Lock and Unlock are requests, not completed state.

enable_loginctl_integration controls optional login1 sleep/wake monitoring. It does not select the lock-tracking method; LockedHint monitoring is automatic with systemd-logind and eLogind.

Running Manually

For testing purposes, you can run Stasis directly from the command line. Make sure you're in a running Wayland session, then simply run:

stasis

This is useful for testing your configuration, but for daily use we strongly recommend setting up the systemd service below for automatic startup.

Systemd Service (Recommended)

The recommended way to run Stasis is as a systemd user service. This ensures Stasis starts automatically with your graphical session and restarts if it crashes.

Provided Service File

Stasis provides a user service file when installed through packages such as the AUR. Enable it once, then start it from your compositor's autostart if your session target does not start it automatically:

systemctl --user enable stasis.service

Then you can start Stasis via your compositors autostart section using the following:

systemctl --user start stasis

Create the Service File

If you installed Stasis manually and want to create a user only service file in your home directory, Create a service file at ~/.config/systemd/user/stasis.service with this content:

[Unit]
Description=Stasis Wayland Idle Manager
PartOf=graphical-session.target
After=graphical-session.target
ConditionPathExists=%t

[Service]
Type=simple
ExecStart=/usr/bin/stasis
ExecReload=/usr/bin/stasis reload
Restart=on-failure
RestartSec=2

[Install]
WantedBy=graphical-session.target

Path Note: The service file above assumes Stasis is installed in /usr/bin/stasis. If you installed Stasis to a different location (e.g., ~/.cargo/bin/stasis), update the ExecStart= line accordingly.

Enable and Start

Enable and start the service with these commands:

# Reload systemd to recognize the new service
systemctl --user daemon-reload

# Enable and start the service
systemctl --user enable --now stasis.service

Now start Stasis from your compositors autostart section e.g. for Hyprland:

exec-once = systemctl --user start stasis