PluelyPluelyDocs

Getting Started

Linux Permissions for Pluely: Mic & Screen Capture Setup

Linux doesn't have one unified permission system the way macOS and Windows do — what you need to check depends on your audio server (PipeWire or PulseAudio) and your display server (X11 or Wayland), which in turn depend on your distribution and desktop environment. This page covers the two things Pluely v1 needs — microphone input and screen capture — and how to verify each on a typical modern Linux setup.

Microphone via PipeWire or PulseAudio

Most current Linux distributions route audio through PipeWire (often with PulseAudio compatibility) or plain PulseAudio. Pluely v1 needs a working input device selected in this layer to hear you in Listen mode and for push-to-talk.

Check your input device is present and selected:

  • Open your desktop's Sound settings (the exact path varies — for example GNOME's Settings → Sound, or KDE's System Settings → Audio) and confirm the correct microphone is chosen as the input device, and that its input level moves when you speak.

  • From a terminal, you can list audio sources directly. On a PipeWire or PulseAudio system:

    pactl list short sources

    Look for your microphone in the list and make sure it isn't muted.

Permission model varies by distro/desktop: Some distributions use PipeWire's session/portal permissions to gate microphone access per application (similar in spirit to macOS), prompting the first time an app requests audio. Others rely entirely on ALSA/PulseAudio device permissions with no per-app prompt at all — if the device is unmuted and selected, any app including Pluely can use it. If you're unsure which model your system uses, the safest first step is always the Sound settings panel above.

Symptom if missing or misconfigured: Listen mode shows no waveform movement for your voice and never transcribes your side of a conversation; push-to-talk does nothing when held.

Screen capture and portal permissions (especially on Wayland)

Screenshots in Ask mode depend on your display server:

  • X11 sessions let Pluely read the screen directly. Region select shows Pluely's own selection overlay on every monitor.
  • Wayland sessions never let an app read the screen, so Pluely asks xdg-desktop-portal (with your desktop's backend, such as the GNOME or KDE portal). A full screenshot shows a permission dialog the first time, and your desktop remembers the answer. Region select opens your desktop's own screenshot picker (region, window, or screen) instead of Pluely's overlay, and the result lands in the chat the same way. Closing the picker simply cancels.

System audio for the other side of a call does not go through the portal. Pluely records the monitor source of your output device through PulseAudio or PipeWire, and your microphone through the same sound server, so it shares the microphone with your meeting app instead of fighting it for the device.

Hiding Pluely from screen shares is not possible on Linux. Neither X11 nor Wayland offers a way for a window to exclude itself from captures, so the overlay is visible in shared screens and recordings on Linux. Move it off the shared screen, or share a single window instead of the whole screen.

How to check/reset portal permissions: The details vary by desktop environment, but the general approach is:

  1. Confirm xdg-desktop-portal (and the desktop-specific backend, e.g. xdg-desktop-portal-gnome or xdg-desktop-portal-kde) is installed — it ships by default on most modern distributions but can be missing on minimal installs.
  2. Look for a screen-sharing or remote-desktop permission setting in your desktop's privacy settings, where previously denied permissions for an app can sometimes be reset.
  3. If a portal prompt was dismissed rather than answered, try the capture again in Pluely to re-trigger it.

Symptom if missing: Screenshot capture fails, returns a blank image, or nothing happens when you try to attach a screen capture; in Listen mode, only your own microphone transcribes and the other side of the call never appears.

Keyboard shortcuts on Wayland

Global shortcuts on Wayland go through the desktop's GlobalShortcuts portal, which needs KDE Plasma 5.27 or later, GNOME 48 or later, or a wlroots desktop (Hyprland, Sway) with its portal installed. Your desktop may ask you to confirm Pluely's shortcuts once, and you can change the keys there too. The Shortcuts page in the dashboard tells you whether the binding worked. On X11 sessions, shortcuts work without any portal.

Two more Wayland limits, set by the compositor rather than Pluely: the move-overlay shortcuts and the saved overlay position do nothing, since Wayland apps cannot position their own windows, and GNOME ignores always-on-top. Drag the overlay where you want it instead.

When in doubt, check the input device first

Because Linux configurations vary so widely, the fastest diagnostic is almost always confirming, at the audio-server level, that a microphone is selected, unmuted, and showing input — that isolates whether an issue is audio configuration versus a screen-capture/portal permission, which need different fixes.

Last updated 2026-07-10 · pluely.com