Linux desktops
What each Linux desktop needs on top of Linux setup, and the issues specific to it. Find your desktop below.
KDE Plasma (Wayland)
Section titled “KDE Plasma (Wayland)”Supported on Plasma 6.
- Make sure
xdg-desktop-portalandxdg-desktop-portal-kderun in your session. - Start Neru. A “Remote Control” prompt appears.
- Tick Enable keyboard, then allow.
- Bind your modes. See Global hotkeys on Wayland.
Neru keeps the grant in remote-desktop.<desktop>.token under
$XDG_STATE_HOME/neru/, by default ~/.local/state/neru/, where <desktop>
is the backend neru doctor shows as display_server, such as
wayland-kde. Each desktop keeps its own grant, so switching between them
does not prompt again. Delete that file, or revoke the permission in System
Settings, to see the prompt again.
Screen-sharing consent
Section titled “Screen-sharing consent”The vision, contour and segment hint strategies read the screen. The first time
one needs a frame, KDE shows a source picker. Pick every screen Neru may read,
because hints on an unshared screen fail. Neru asks for monitors only, not
the pointer, and a capture never raises the picker by itself.
Neru keeps this grant in screen-cast.<desktop>.token in the same directory.
Delete that file, or revoke it in System Settings > Apps & Window Management >
Application Permissions, to see the picker again.
“could not establish a libei input session via the RemoteDesktop portal”
Section titled ““could not establish a libei input session via the RemoteDesktop portal””Approve the consent prompt before it times out. If you denied it, revoke and re-grant it in System Settings, and check the portal services run. After a revoke, Neru drops its stale token and prompts again.
“key feeding unavailable: the RemoteDesktop portal session did not grant a keyboard device”
Section titled ““key feeding unavailable: the RemoteDesktop portal session did not grant a keyboard device””The grant is missing the keyboard. Clear it, restart the daemon, and tick Enable keyboard in the new prompt. To clear it:
- Plasma 6.5 or later: in System Settings > Applications > Remote
Desktop, remove any saved
nerupermission. - Plasma 6.3 or later, from a terminal:
flatpak permission-remove kde-authorized remote-desktop "". This clears KDE’s portal permissions for every host app, flatpak or not.
COSMIC (Wayland)
Section titled “COSMIC (Wayland)”Supported on cosmic-comp. Pointer input needs xdg-desktop-portal-cosmic 1.7
or later.
- Check
xdg-desktop-portal-cosmicis 1.7 or later. Fedora 44 ships 1.6, where the daemon starts but every pointer action fails and names the missing portal. - Start Neru and approve the prompts, as on KDE, including screen-sharing consent.
- Bind your modes. See Global hotkeys on Wayland.
wlroots compositors
Section titled “wlroots compositors”Which compositors take this backend, and how Neru tells, is under Supported desktops. One not listed there works if it has the protocols under Checking compositor protocols.
Follow Linux setup, including the input group and
the /dev/uinput rule. What breaks without them is in
Running without the permissions.
Hints in native apps are offset
Section titled “Hints in native apps are offset”Hints read window positions from the compositor.
- Sway, Hyprland, niri: the compositor reports positions, so hints line up.
- niri tiled windows: niri 26.04 and earlier report no position for them (niri#2381), so hints are misaligned. Floating and fullscreen windows are fine. Releases after 26.04 report tiled windows too (niri#4711), and hints line up.
- River, Wayfire, labwc: the compositor reports no positions, so Neru places hints in native apps relative to the window, not the screen.
On River, Wayfire and labwc, --capture-scope window covers the whole screen
instead of the window, for grid modes, vision, contour and segment alike. Neru logs
a warning each time, and neru query window and move_mouse --window refuse.
Grid modes with the default screen scope are not affected. See also
Known gaps.
X11 sessions
Section titled “X11 sessions”[hotkeys] work with no compositor binding or device permission. The
backend’s limits, such as no modifier passthrough, are in the
capability matrix.
GNOME (Wayland)
Section titled “GNOME (Wayland)”Supported with Xwayland and the Neru GNOME Shell extension. Tested on GNOME Shell 50. The extension declares GNOME Shell 45 to 50, and the older versions are untested.
- Make sure Xwayland is enabled. The daemon refuses to start without
DISPLAY, because its overlay is an Xwayland window. - Follow Linux setup. On GNOME the
inputgroup is required, since keyboard capture has no fallback. - Start Neru. It installs and enables its extension, and warns once.
- Log out and back in, so GNOME Shell loads the extension.
- Approve the input and screen-sharing prompts, as on KDE. GNOME grants the keyboard with the pointer, so there is no box to tick.
Until you log back in, modes work, but per-app config does not apply, hints in
native apps are offset, and neru doctor reports app_watcher as a stub.
The extension
Section titled “The extension”The extension neru@y3owk1n.github.io tells Neru which window has focus, its
app id, title and position. It reads only the focused window, and neither logs
nor stores anything. Neru installs it in
$XDG_DATA_HOME/gnome-shell/extensions/neru@y3owk1n.github.io/. Neru rewrites
it only when a release changes it, and never re-enables it if you disable it.
The overlay is offset on a scaled monitor
Section titled “The overlay is offset on a scaled monitor”Mutter’s experimental xwayland-native-scaling feature moves the overlay on
scaled monitors. Turn it off. The daemon warns at startup when it sees this.
Budgie, Cinnamon and Pantheon
Section titled “Budgie, Cinnamon and Pantheon”Budgie identifies as GNOME, so Neru gives it this backend. That path is untested, and Budgie’s shell cannot load the extension. For Cinnamon and Pantheon, see Supported desktops.
Global hotkeys on Wayland
Section titled “Global hotkeys on Wayland”Bind modes in one of two ways. X11 needs neither, since its [hotkeys] work
with no permissions.
Neru’s [hotkeys] | Compositor keybindings | |
|---|---|---|
| Needs | The input group, see Linux setup | Nothing |
| The focused app sees the chord | No, if /dev/uinput is writable | No |
| Works while a mode is open | Yes | No |
With [hotkeys], the daemon logs
Wayland global hotkeys enabled via evdev; config keybindings are active at
startup, or a warning naming the input group.
Compositor bindings
Section titled “Compositor bindings”# Sway: ~/.config/sway/configbindsym $mod+Shift+h exec neru hintsbindsym $mod+Shift+g exec neru gridbindsym $mod+Shift+s exec neru scrollbind = $mod SHIFT, H, exec, neru hintsbind = $mod SHIFT, G, exec, neru gridbind = $mod SHIFT, S, exec, neru scrollbinds { Mod+Shift+H { spawn-sh "neru hints"; } Mod+Shift+G { spawn-sh "neru grid"; } Mod+Shift+S { spawn-sh "neru scroll"; } Mod+Shift+R { spawn-sh "neru recursive_grid"; }}On KDE Plasma, add them in System Settings > Shortcuts > Custom Shortcuts
with the binary’s full path, such as /home/<you>/.local/bin/neru hints.
Checking compositor protocols
Section titled “Checking compositor protocols”Run this inside the graphical session:
wayland-info | grep -E 'zwlr_layer_shell|zwlr_virtual_pointer|zwp_virtual_keyboard|zwlr_screencopy|fake_input|xdg_output'A wlroots compositor needs zwlr_layer_shell_v1 and
zwlr_virtual_pointer_v1. Neru refuses to start on a compositor it does not
recognize. To help add support for one, see the
porting guide.
Which protocols each supported desktop has is in
platform internals.