swayidle

https://github.com/swaywm/swayidle
Admin
swayidle is an idle management daemon for Sway/Wayland compositors that detects user inactivity and...
Tokens:2,098
Snippets:32
Trust Score:9.1
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Compile and install swayidle

Source: https://github.com/swaywm/swayidle/blob/master/README.md

Use these commands to configure, build, and install the project from the source directory.

```bash
meson build/
ninja -C build/
sudo ninja -C build/ install
```

--------------------------------

### Example configuration file

Source: https://context7.com/swaywm/swayidle/llms.txt

Configuration files use the same syntax as command-line arguments, with one event per line.

```bash
# Example config file: ~/.config/swayidle/config

# Lock screen after 5 minutes
timeout 300 'swaylock -f -c 000000'

# Turn off displays after 10 minutes
timeout 600 'swaymsg "output * power off"' resume 'swaymsg "output * power on"'

# Lock before sleep
before-sleep 'swaylock -f -c 000000'

# Handle system lock signals
lock 'swaylock -f -c 000000'

# Set idle hint for logind
idlehint 300
```

--------------------------------

### Enable and Start Swayidle Systemd Service

Source: https://context7.com/swaywm/swayidle/llms.txt

Commands to enable the swayidle systemd service to start on login and start it immediately.

```bash
# Enable and start the service
systemctl --user enable swayidle.service
systemctl --user start swayidle.service
```

--------------------------------

### Basic Screen Locking Setup with Swayidle

Source: https://context7.com/swaywm/swayidle/llms.txt

Configure swayidle to lock the screen after 5 minutes, turn off the display after 10 minutes, and lock before sleep.

```bash
swayidle -w \
    timeout 300 'swaylock -f -c 000000' \
    timeout 600 'swaymsg "output * power off"' \
        resume 'swaymsg "output * power on"' \
    before-sleep 'swaylock -f -c 000000'
```

--------------------------------

### Integrate Swayidle into Sway Configuration

Source: https://context7.com/swaywm/swayidle/llms.txt

Add swayidle to your Sway configuration file to start it automatically when Sway launches. Also includes a manual lock keybinding.

```bash
# ~/.config/sway/config

# Start swayidle for idle management
exec swayidle -w \
    timeout 300 'swaylock -f -c 000000' \
    timeout 600 'swaymsg "output * power off"' resume 'swaymsg "output * power on"' \
    before-sleep 'swaylock -f -c 000000'

# Manual lock keybinding
bindsym $mod+l exec swaylock -f -c 000000
```

--------------------------------

### Select Wayland seat

Source: https://context7.com/swaywm/swayidle/llms.txt

The -S flag targets a specific seat for monitoring in multi-seat setups.

```bash
# Monitor a specific seat
swayidle -S seat0 timeout 300 'swaylock -f'
```

--------------------------------

### Systemd Service for Swayidle

Source: https://context7.com/swaywm/swayidle/llms.txt

Set up swayidle as a systemd user service for automatic startup on login. Ensure the service file is placed in ~/.config/systemd/user/.

```ini
# ~/.config/systemd/user/swayidle.service
[Unit]
Description=Idle manager for Wayland
Documentation=man:swayidle(1)
PartOf=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/swayidle -w \
    timeout 300 'swaylock -f -c 000000' \
    timeout 600 'swaymsg "output * power off"' resume 'swaymsg "output * power on"' \
    before-sleep 'swaylock -f -c 000000'
Restart=on-failure
RestartSec=1

[Install]
WantedBy=sway-session.target
```

--------------------------------

### Specify custom configuration file

Source: https://context7.com/swaywm/swayidle/llms.txt

Use the -C flag to point to a non-default configuration file path.

```bash
# Use a custom config file
swayidle -C /path/to/custom/config
```

--------------------------------

### Enable debug mode

Source: https://context7.com/swaywm/swayidle/llms.txt

The -d flag provides verbose output for troubleshooting.

```bash
# Run with debug output
swayidle -d timeout 300 'swaylock -f'
```

--------------------------------

### Handle after-resume events

Source: https://context7.com/swaywm/swayidle/llms.txt

Execute commands after the system wakes from sleep.

```bash
# Refresh displays and notify on resume
swayidle after-resume 'swaymsg "output * enable" && notify-send "Resumed from sleep"'

# Combined sleep/resume handling
swayidle \
    before-sleep 'swaylock -f' \
    after-resume 'notify-send "Welcome back"'
```

--------------------------------

### Configure timeout events

Source: https://context7.com/swaywm/swayidle/llms.txt

Define actions for inactivity durations, including optional resume commands.

```bash
# Lock screen after 5 minutes of inactivity
swayidle timeout 300 'swaylock -f -c 000000'

# Turn off displays after 10 minutes, turn back on when resumed
swayidle timeout 600 'swaymsg "output * power off"' \
    resume 'swaymsg "output * power on"'

# Multiple timeouts: lock at 5 min, turn off display at 10 min
swayidle \
    timeout 300 'swaylock -f -c 000000' \
    timeout 600 'swaymsg "output * power off"' \
        resume 'swaymsg "output * power on"'
```

--------------------------------

### Handle before-sleep events

Source: https://context7.com/swaywm/swayidle/llms.txt

Execute commands prior to system sleep; requires systemd or elogind.

```bash
# Lock screen before sleep
swayidle before-sleep 'swaylock -f -c 000000'

# Lock and notify before sleep
swayidle before-sleep 'swaylock -f && notify-send "Going to sleep"'
```

--------------------------------

### Handle unlock events

Source: https://context7.com/swaywm/swayidle/llms.txt

Respond to session unlock signals from logind.

```bash
# Perform actions on unlock
swayidle unlock 'notify-send "Session unlocked"'

# Combined lock/unlock handling
swayidle \
    lock 'swaylock -f' \
    unlock 'swaymsg "output * enable"'
```

--------------------------------

### Graceful shutdown via signal

Source: https://context7.com/swaywm/swayidle/llms.txt

Send SIGTERM or SIGINT to exit cleanly, executing pending resume commands.

```bash
# Gracefully stop swayidle (runs pending resume commands)
pkill swayidle
```

--------------------------------

### Trigger immediate idle via signal

Source: https://context7.com/swaywm/swayidle/llms.txt

Send SIGUSR1 to force an immediate idle state.

```bash
# Get swayidle PID and trigger immediate idle
pkill -USR1 swayidle

# Or using the PID directly
kill -USR1 $(pgrep swayidle)
```

--------------------------------

### Handle lock events

Source: https://context7.com/swaywm/swayidle/llms.txt

Respond to session lock signals from logind.

```bash
# Respond to system lock requests
swayidle lock 'swaylock -f -c 000000'

# This allows locking via: loginctl lock-session
```

--------------------------------

### Use wait mode

Source: https://context7.com/swaywm/swayidle/llms.txt

The -w flag forces the daemon to wait for command completion, which is critical for ensuring lock commands finish before sleep.

```bash
# Wait for swaylock to finish locking before releasing inhibitor
swayidle -w \
    timeout 300 'swaylock -f -c 000000' \
    before-sleep 'swaylock -f -c 000000'
```

--------------------------------

### Set idlehint property

Source: https://context7.com/swaywm/swayidle/llms.txt

Update the logind IdleHint property to notify other services of session status.

```bash
# Set idle hint after 5 minutes for logind-aware applications
swayidle idlehint 300
```
Tokens:
Raw