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 if you use enable_dbus_inhibit, loginctl lock tracking, lid events, or suspend/resume integration.

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 normally tracks a lock step by waiting for the configured locker process to exit. If your locker daemonizes or forks immediately, Stasis can interpret that as an immediate unlock.

Do not daemonize unless you also enable loginctl tracking. Remove options like swaylock -f when possible. If your setup requires a backgrounding locker, use enable_loginctl true and a wrapper script.

Wrapper Script Pattern

#!/usr/bin/env bash
# Tell logind we are locking; Stasis listens for this when enable_loginctl is true.
loginctl lock-session

# Run your locker in the background if it must daemonize or fork.
swaylock -f

Save this as ~/.local/bin/stasis-lock.sh, make it executable, then reference it from your config:

default:
  enable_loginctl true

  lock_screen:
    timeout 300
    command "~/.local/bin/stasis-lock.sh"
  end
end

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