marceloeatworld/hyprland-ai-skill
hyprland
FlaggedThis skill should be used when the user asks about "Hyprland configuration", "hyprland.lua", "hyprland.conf", "Hyprland Lua config", "hyprctl", "Hyprland keybinds", "Hyprland window rules", "Hyprland monitors", "Hyprland dispatchers", "Hyprland animations", "Hyprland workspaces", "Hyprland IPC", "Hyprland plugins", "hyprlock", "hypridle", "hyprpaper", "hyprcursor", "hyprpicker", "hyprsunset", "xdg-desktop-portal-hyprland", "Hyprland on NixOS", "Hyprland Home Manager", "Hyprland layouts", "Hyprland dwindle", "Hyprland master layout", "Hyprland FAQ", "Hyprland performance", "Hyprland Nvidia", "Hyprland screen sharing", "Hyprland special workspace", "Hyprland smart gaps", "Hyprland multi-monitor", "Hyprland tearing", or any topic related to configuring, troubleshooting, or extending the Hyprland Wayland compositor and its ecosystem tools.
references/permissions.md
View on GitHub<!-- source: https://wiki.hypr.land/configuring/core/advanced-configuration/permissions -->
<!-- wiki commit: 41c7222 (2026-11-20 18:16:21 +0100) -->
<!-- auto-generated by scripts/generate-references.sh - DO NOT EDIT MANUALLY -->
---
weight: 40
title: Permissions
---
If you have `hyprland-guiutils` installed, you can make use of Hyprland's built-in permission system.
For now, it only has a few permissions, but it might include more in the future.
> [!TIP]
> If you care about this permissions system, you probably also care about blocking access to Hyprland's [IPC sockets](../../../../ipc).
> Hyprland itself cannot enforce this; consult the documentation for your application sandbox of choice.
## Permissions
Permissions work a bit like Android ones.
If an app tries to do something sensitive with the compositor (Hyprland), Hyprland will pop up a notification asking you if you want to let it do that.
> [!NOTE]
> Before setting up permissions, make sure you enable them by setting `hl.config({ ecosystem = { enforce_permissions = true } })`, as it's disabled by default.
### Configuring permissions
> [!IMPORTANT]
> Permissions set up in the config are **not** reloaded on-the-fly and require a Hyprland restart for security reasons.
Configuring them is simple:
```lua
hl.permission({ binary, type, mode })
```
For example:
```lua
hl.permission({ binary = "/usr/bin/grim", type = "screencopy", mode = "allow" })
```
will allow `/usr/bin/grim` to always capture your screen without asking, and
```lua
hl.permission({ binary = "/usr/bin/appsuite-.*", type = "screencopy", mode = "allow" })
```
will allow any app whose path starts with `/usr/bin/appsuite-` to capture your screen without asking.
### Permission modes
There are 3 modes:
- `allow`: Don't ask, just allow the app to proceed.
- `ask`: Pop up a notification every time the app tries to do something sensitive.
These popups let you **Deny**, **Allow until the app exits**, or **Allow until Hyprland exits**.
- `deny`: Don't ask, always deny the application access.
### Permission list
#### screencopy
- Default: **ASK**
- Access to your screen _without_ going through xdg-desktop-portal-hyprland. Examples include: `grim`, `wl-screenrec`, `wf-recorder`.
- If denied, will render a black screen with a "permission denied" text.
- Why deny? For apps/scripts that might maliciously try to capture your screen without your knowledge by using Wayland protocols directly.
#### plugin
- Default: **ASK**
- Access to load a plugin. Can be either a regex for the app binary, or plugin path.
- Do _not_ allow `hyprctl` to load your plugins by default (attacker could issue `hyprctl plugin load /tmp/my-malicious-plugin.so`) - use either `deny` to disable or `ask` to be prompted.
#### keyboard
- Default: **ALLOW**
- Access to connecting a new keyboard. Regex of the device name.
- If you want to disable all keyboards not matching a regex, make a rule that sets `DENY` for `.*` _as the last keyboard permission rule_.
- Why deny? Rubber duckies, malicious virtual/USB keyboards.
#### cursorpos
- Default: **ASK**
- Access to your cursor position and cursor image via Wayland protocols directly.
- Why deny? Prevents apps from silently tracking where your cursor is without going through xdg-desktop-portal.
#### input-capture
- Default: **ASK**
- Access to capture all input events from the compositor (keyboard, pointer, touch).
- Why deny? Prevents apps from maliciously capturing all user input without your consent.
## Notes
### Portals
**xdg-desktop-portal** implementations (including XDPH) are just regular applications.
They will go through permissions too.
You might want to consider adding a rule like this:
```lua
hl.permission({ binary = "/usr/(lib|libexec|lib64)/xdg-desktop-portal-hyprland", type = "screencopy", mode = "allow" })
```
if you are not allowing screencopy for all apps.
### NixOS
NixOS does not have static paths for the binaries, so regex must be used.
These example rules allow `grim` and `xdg-desktop-portal-hyprland` to copy the screen:
```lua
hl.permission({ binary = "/nix/store/[a-z0-9]{32}-grim-[0-9.]*/bin/grim", type = "screencopy", mode = "allow" })
hl.permission({ binary = "/nix/store/[a-z0-9]{32}-xdg-desktop-portal-hyprland-[0-9.]*/libexec/.xdg-desktop-portal-hyprland-wrapped", type = "screencopy", mode = "allow" })
```
When rendering the configuration with Nix itself, string interpolation can also be used.
Be aware that if the path contains special regex characters (e.g. `+`) they need to be escaped:
```lua
hl.permission({ binary = "${lib.getExe pkgs.grim}", type = "screencopy", mode = "allow" })
hl.permission({ binary = [[${lib.escapeRegex (lib.getExe config.programs.hyprlock.package)}]], type = "screencopy", mode = "allow" })
hl.permission({ binary = [[${pkgs.xdg-desktop-portal-hyprland}/libexec/\.xdg-desktop-portal-hyprland-wrapped]], type = "screencopy", mode = "allow" })
```
### BSD
On some **BSD** systems paths might not work.
In such cases, you might want to disable permissions altogether, by setting:
```lua
hl.config({
ecosystem = {
enforce_permissions = false
}
})
```
Otherwise, you will have no _config_ control over permissions (popups will still work, although they will not show paths, and "remember" will not be available).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |