Quick Start

Prerequisites

Stasis requires access to input devices to monitor idle activity and brightness controls on laptops. Without these group memberships, Stasis will fail to start or function properly.

Group Setup

Check Current Groups

First, check which groups you're currently in:

groups $USER

You should see output like:

dustin : dustin wheel audio input video storage

Add Missing Groups

If input is missing, add yourself:

sudo usermod -aG input $USER

If you're on a laptop and video is missing, add it as well:

sudo usermod -aG video $USER

Or add both at once:

sudo usermod -aG input,video $USER

After logging back in, verify the groups were added:

groups $USER

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 already provides a service file if you installed it via the AUR on Arch Linux To start the service file with your desired compositor first enable it using:

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
ConditionEnvironment=WAYLAND_DISPLAY

[Service]
Type=simple
ExecStart=/usr/bin/stasis
Restart=on-failure

[Install]
WantedBy=graphical-session.target

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

Troubleshooting

Service stuck in "activating" state

This usually means the WAYLAND_DISPLAY environment variable isn't available yet. The service file includes a wait condition, but if issues persist:

echo $WAYLAND_DISPLAY
ls -la /run/user/$(id -u)/wayland-*

Make sure your compositor has started and the Wayland socket exists before starting Stasis.

Service fails with exit code 203 (EXEC)

This means systemd can't execute the binary. Common causes:

• The binary doesn't exist at the specified path
• The binary isn't executable (chmod +x may be needed)
• The path in ExecStart= is wrong

Verify the binary location and update the service file:

which stasis
# Then update ExecStart= in the service file to match

Brightness controls (brightnessctl/light) stop working

This is usually caused by missing environment variables. The updated service file imports all necessary environment variables from your session. If issues persist:

• Make sure you're in the video group
• Restart the service after editing: systemctl --user restart stasis.service
• Check logs for errors: journalctl --user -u stasis.service -f

Permission denied errors

If you see permission errors in the logs:

• Verify you're in the required groups: groups $USER
• Make sure you logged out and back in after adding groups
• Check that /dev/input/* devices are accessible

Starting from compositor config vs systemd

You can start Stasis from your compositor configuration instead of systemd, but not both at the same time. If using compositor startup:

# Hyprland example:
exec-once = sleep 2 && stasis

# Niri example:
spawn-at-startup "stasis"