Stasis

Configuration

Overview

Stasis uses a .rune configuration file located at $XDG_CONFIG_HOME/stasis/stasis.rune (typically ~/.config/stasis/stasis.rune). On first run, Stasis automatically generates a default configuration file with sensible defaults.

The default configuration template is located at /etc/stasis/stasis.rune.

The configuration is structured hierarchically with a main stasis: block containing all settings, actions, and laptop-specific power profiles.

Global Settings

At the top of your config, you can define global variables and metadata:

@author "Your Name"
@description "Stasis configuration file"

# Define global variables for reuse
default_timeout 300  # 5 minutes

Global variables can be referenced throughout your configuration, making it easier to maintain consistent values.

Stasis Block

All configuration lives within the stasis: block:

stasis:
  pre_suspend_command "hyprlock"
  monitor_media true
  ignore_remote_media true
  respect_idle_inhibitors true
  
  # ... action blocks and laptop configs
end

Pre-Suspend Command

pre_suspend_command runs before the system suspends. Commonly used to lock the screen:

pre_suspend_command "hyprlock"

Media Monitoring

Media Playback

Control whether Stasis monitors media playback to prevent idle actions:

monitor_media true
ignore_remote_media true
  • monitor_media - When true, active media playback prevents idle timeouts
  • ignore_remote_media - Ignores media from remote sources (KDEConnect, Spotify remote play, etc.)

Media Blacklist

Ignore specific media players when checking for active playback:

media_blacklist ["spotify", "rhythmbox"]

Inhibitors

Idle Inhibitors

Respect system-wide idle inhibitors from other applications:

respect_idle_inhibitors true

Application Inhibitors

Specify applications that should prevent idle actions when active. Supports exact names and regex patterns:

inhibit_apps [
  "vlc"
  "Spotify"
  "mpv"
  r".*\.exe"           # Any .exe (Wine/Proton)
  r"steam_app_.*"      # Steam games
  r"firefox.*"         # Firefox windows
]
Regex Pattern Guidelines:
  • Use raw string syntax: r"pattern" for all regex patterns
  • Escape special characters properly: \. for literal dots, \d+ for digits
  • Use .* for wildcard matching
  • Use ^ for start-of-string and $ for end-of-string anchors
  • Test your patterns with verbose logging to ensure they match correctly
  • NOTE: Stasis uses the regex crate for pattern matching

Laptop Settings

Lid Actions

Configure what happens when the laptop lid closes or opens:

lid_close_action "lock-screen"
lid_open_action "wake"
Available lid_close_action options:
  • lock-screen - Lock the screen
  • suspend - Suspend the system
  • custom - Run a custom command
  • ignore - Do nothing
Available lid_open_action options:
  • wake - Wake the system
  • custom - Run a custom command
  • ignore - Do nothing

Debounce

Prevent rapid lid open/close events from triggering multiple actions. Default is 3 seconds:

debounce_seconds 4

Idle Actions

Stasis supports several built-in action types that trigger after periods of inactivity. Each action block has three key parameters:

  • timeout - Seconds of idle time before triggering (required)
  • command - Command to run when action triggers (required)
  • resume-command - Command to run when activity resumes (optional)

Built-in Action Types

  • lock_screen / lock-screen - Lock the session
  • dpms - Display power management (screen off)
  • suspend - System suspend
  • brightness - Adjust screen brightness (laptop only)
  • custom-* - Custom actions with any name

Desktop Actions

Desktop actions apply to all devices (desktops and laptops when not in AC/battery profiles). Define them directly under the stasis: block:

lock_screen:
  timeout 300  # 5 minutes
  command "loginctl lock-session"
  resume-command "notify-send 'Welcome Back $env.USER!'"
end

dpms:
  timeout 60  # 1 minute after lock
  command "niri msg action power-off-monitors"
  resume-command "niri msg action power-on-monitors"
end

suspend:
  timeout 1800  # 30 minutes
  command "systemctl suspend"
  resume-command None
end
🔒 loginctl Integration: When using loginctl lock-session as your lock command, you MUST specify the actual locker via the lock-command parameter: 
lock_screen:
  timeout 300
  command "loginctl lock-session"
  lock-command "swaylock"  # REQUIRED when using loginctl
end

The lock-command is required when command is set to loginctl lock-session. This tells loginctl which locker to use when managing the lock state.

Note: You can lock your session at any time with loginctl lock-session even when using Stasis without needing lock-command in the config.

AC & Battery Profiles

Laptops can define separate action profiles for AC power and battery power. These override desktop actions when applicable.

AC Power Profile

Actions when plugged in:

on_ac:
  # Instant action (0 second timeout)
  custom-brightness-instant:
    timeout 0
    command "brightnessctl set 100%"
  end
  
  brightness:
    timeout 120  # 2 minutes
    command "brightnessctl set 30%"
  end
  
  dpms:
    timeout 60
    command "niri msg action power-off-monitors"
  end
  
  lock_screen:
    timeout 120
    command "swaylock"
  end
  
  suspend:
    timeout 300
    command "systemctl suspend"
  end
end

Battery Profile

More aggressive timeouts to save battery:

on_battery:
  custom-brightness-instant:
    timeout 0
    command "brightnessctl set 40%"
  end
  
  brightness:
    timeout 60  # 1 minute
    command "brightnessctl set 20%"
  end
  
  dpms:
    timeout 30  # 30 seconds
    command "niri msg action power-off-monitors"
    resume-command "niri msg action power-on-monitors"
  end
  
  lock_screen:
    timeout 120  # 2 minutes
    command "swaylock"
    resume-command "notify-send 'Welcome back $env.USER!'"
  end
  
  suspend:
    timeout 120  # 2 minutes
    command "systemctl suspend"
  end
end
💡 Tip: Define instant actions (timeout 0) first to prevent them from retriggering after longer timeouts complete.

Full Example Configuration

Here's the complete default configuration shipped with Stasis:

@author "Dustin Pilgrim"
@description "Stasis configuration file"

# Global variable
default_timeout 300  # 5 minutes

stasis:
  pre_suspend_command "hyprlock"
  monitor_media true
  ignore_remote_media true
  
  # Optional: ignore specific media players
  #media_blacklist ["spotify"]
  
  respect_idle_inhibitors true
  
  # Laptop lid behavior
  #lid_close_action "lock-screen"  # lock-screen | suspend | custom | ignore
  #lid_open_action "wake"          # wake | custom | ignore
  
  # Debounce: default is 3s; can be customized if needed
  #debounce_seconds 4
  
  # Applications that prevent idle when active
  inhibit_apps [
    "vlc"
    "Spotify"
    "mpv"
    r".*\.exe"
    r"steam_app_.*"
    r"firefox.*"
  ]
  
  # Desktop-only idle actions (applies to all devices)
  lock_screen:
    timeout 300  # 5 minutes
    command "loginctl lock-session"
    resume-command "notify-send 'Welcome Back $env.USER!'"
    lock-command "swaylock"
  end
  
  dpms:
    timeout 60  # 1 minute
    command "niri msg action power-off-monitors"
    resume-command "niri msg action power-on-monitors"
  end
  
  suspend:
    timeout 1800  # 30 minutes
    command "systemctl suspend"
    resume-command None
  end
  
  # Laptop-only AC actions
  on_ac:
    # Instant brightness adjustment
    custom-brightness-instant:
      timeout 0
      command "brightnessctl set 100%"
    end
    
    brightness:
      timeout 120  # 2 minutes
      command "brightnessctl set 30%"
    end
    
    dpms:
      timeout 60  # 1 minute
      command "niri msg action power-off-monitors"
    end
    
    lock_screen:
      timeout 120  # 2 minutes
      command "swaylock"
    end
    
    suspend:
      timeout 300  # 5 minutes
      command "systemctl suspend"
    end
  end
  
  # Laptop-only battery actions
  on_battery:
    custom-brightness-instant:
      timeout 0
      command "brightnessctl set 40%"
    end
    
    brightness:
      timeout 60  # 1 minute
      command "brightnessctl set 20%"
    end
    
    dpms:
      timeout 30  # 30 seconds
      command "niri msg action power-off-monitors"
      resume-command "niri msg action power-on-monitors"
    end
    
    lock_screen:
      timeout 120  # 2 minutes
      command "swaylock"
      resume-command "notify-send 'Welcome back $env.USER!'"
    end
    
    suspend:
      timeout 120  # 2 minutes
      command "systemctl suspend"
    end
  end
end