Enabling keyboard/mouse access on Wayland

This page is for Linux users on a Wayland compositor. If you’re unsure if you’re on Wayland or X11, run echo $XDG_SESSION_TYPE in a terminal.

⚠️ Security Note / Context

Wayland’s security model prevents apps from having low-level access to keyboard and mouse devices. However, Mouseless requires this low-level access to: utilize global hotkeys; suppress input to apps without stealing focus; and generate mouse events.

This means you must disable Wayland’s extra restrictions around keyboard/mouse access for Mouseless to work, i.e. adopt a security model equivalent to X11’s. This affects all programs run by your user, not just Mouseless, though there are some alternatives for advanced users mentioned at the bottom.

Disclaimer: The developers of Mouseless are not responsible for any issues that may arise from changing your system configuration or using elevated privileges (sudo). Do so at your own risk.

Method 1 (udev rules)

Add these rules to allow your user to access input devices:

sudo tee /etc/udev/rules.d/99-mouseless-input.rules <<EOF
# Output: Virtual device creation
KERNEL=="uinput", GROUP="$USER", MODE:="0660"

# Input: Physical device reading
KERNEL=="event*", GROUP="$USER", NAME="input/%k", MODE:="0660"
EOF

Reload the system rules:

sudo udevadm control --reload-rules && sudo udevadm trigger

Method 2 (fallback)

If you still see udev-related errors or ‘no keyboards detected’ errors when starting Mouseless, this method should work for you.

Undo rule creation from step 1:

sudo rm /etc/udev/rules.d/99-mouseless-input.rules

Create a systemd temporary file configuration:

# Forces current user/group ownership on input devices
sudo tee /etc/tmpfiles.d/mouseless-input.conf <<EOF
z /dev/uinput       0660 $USER $(id -gn) - -
z /dev/input/event* 0660 $USER $(id -gn) - -
EOF

Apply the permissions:

sudo systemd-tmpfiles --create /etc/tmpfiles.d/mouseless-input.conf

Hotplugging note: The changes made in method 2 persist across reboots, but if you plug in any keyboards after startup, you may need to run the systemd-tmpfiles command (step 3) again to apply permissions to them, then restart Mouseless.

Alternatives (advanced)

Run as root

Instead of changing Wayland’s input security, you can simply run Mouseless with sudo. The security implication here is that if a malicious process hijacks the Mouseless process, it will have root access to your system.

Create a dedicated user

You might be able to create a separate system user and assign the needed permissions, then run Mouseless as that user. However, running a GUI app as a different user on Wayland is complex and requires manual configuration to allow the app to connect to your display session.

If you figure out a reliable configuration for this, please share! I’d be happy to post community-contributed guides, even if they are specific to certain distros or compositors.

Keyboard shortcuts