Hyprland

Add the following settings to your Hyprland Lua configuration file (usually found at ~/.config/hypr/hyprland.lua).

Autostart Noctalia

Add this to your hyprland.start event hook:

hl.on("hyprland.start", function()
  hl.exec_cmd("noctalia")
end)

Compositor Settings

Add the following to your existing hl.config({}) block. These settings are for general window appearance and functionality.

hl.config({
  general = {
    gaps_in = 5,
    gaps_out = 10,
  },

  decoration = {
    rounding = 20,
    rounding_power = 2,

    shadow = {
      enabled = true,
      range = 4,
      render_power = 3,
      color = 0xee1a1a1a,
    },

    blur = {
      enabled = true,
      xray = true,
      size = 3,
      passes = 2,
      vibrancy = 0.1696,
    },
  },
})

Persistent Workspaces

For the best workspace indicator behavior, make your regular Hyprland workspaces persistent. This keeps empty workspaces visible in Noctalia instead of only showing workspaces that currently contain windows.

Update the monitor name and workspace list to match your setup. You can find more syntax and examples in the official Workspace Rules documentation.

hl.workspace_rule({ workspace = "1", monitor = "DP-1", persistent = true, default_name = "web" })
hl.workspace_rule({ workspace = "2", monitor = "DP-1", persistent = true, default_name = "code" })
hl.workspace_rule({ workspace = "3", monitor = "DP-1", persistent = true, default_name = "chat" })
hl.workspace_rule({ workspace = "4", monitor = "DP-1", persistent = true, default_name = "game" })
hl.workspace_rule({ workspace = "5", monitor = "DP-1", persistent = true, default_name = "design" })

IPC Keybinds

Add these binds to your hyprland.lua:

local mainMod = "SUPER"
local ipc = "noctalia msg "

-- Core binds
hl.bind(mainMod .. "+Space", hl.dsp.exec_cmd(ipc .. "panel-toggle launcher"))
hl.bind(mainMod .. "+S", hl.dsp.exec_cmd(ipc .. "panel-toggle control-center"))
hl.bind(mainMod .. "+comma", hl.dsp.exec_cmd(ipc .. "settings-toggle"))
hl.bind("ALT + Tab", hl.dsp.exec_cmd(ipc .. "window-switcher hold"))
hl.bind("ALT + SHIFT + Tab", hl.dsp.exec_cmd(ipc .. "window-switcher hold reverse"))

-- Media keys
hl.bind("XF86AudioRaiseVolume", hl.dsp.exec_cmd(ipc .. "volume-up"))
hl.bind("XF86AudioLowerVolume", hl.dsp.exec_cmd(ipc .. "volume-down"))
hl.bind("XF86AudioMute", hl.dsp.exec_cmd(ipc .. "volume-mute"))
hl.bind("XF86MonBrightnessUp", hl.dsp.exec_cmd(ipc .. "brightness-up"))
hl.bind("XF86MonBrightnessDown", hl.dsp.exec_cmd(ipc .. "brightness-down"))

-- Noctalia Settings
hl.window_rule({
    match = { class = "dev.noctalia.Noctalia" },
    float = true,
    size = { 1080, 920 },
})

Layer Animations

Disable Hyprland’s built-in layer animations for Noctalia. Noctalia animates its own surfaces; Hyprland’s layersIn/layersOut animations run on top of them and cause visual glitches, such as a panel tearing when it is reopened while still closing. Add this rule even if you do not use blur.

hl.layer_rule({
  name = "noctalia-no-anim",
  match = {
    namespace = "^noctalia-(bar-.+|notification|dock|panel|attached-panel|osd|window-switcher)$",
  },
  no_anim = true,
})

Blur

Enable blur for Noctalia’s bar, panels, dock, and notifications.

Blurred Noctalia surfaces

hl.layer_rule({
  name = "noctalia-blur",
  match = {
    namespace = "^noctalia-(bar-.+|notification|dock|panel|attached-panel|osd|window-switcher)$",
  },
  ignore_alpha = 0.5,
  blur = true,
  blur_popups = true,
})

Permissions

If you use Hyprland’s permission system (ecosystem.enforce_permissions = true), allow Noctalia to capture the screen and to connect its virtual keyboard. Without these rules, Hyprland asks for permission or denies access, depending on your other rules.

• screencopy is used for screenshots and lock screen desktop capture.
• keyboard is used for clipboard and launcher auto-paste. Hyprland names Noctalia’s virtual keyboard hl-virtual-keyboard-noctalia.

hl.config({
  ecosystem = {
    enforce_permissions = true,
  },
})

hl.permission("^/usr/bin/noctalia$", "screencopy", "allow")
hl.permission("^hl-virtual-keyboard-noctalia$", "keyboard", "allow")

If Noctalia is installed somewhere else, for example /usr/local/bin/noctalia, change the binary path to match. Run readlink -f "$(command -v noctalia)" to find the path. If you have a catch-all keyboard rule such as hl.permission(".*", "keyboard", "deny"), keep it after the Noctalia rule.

Hyprland does not reload permission rules on config reload. Restart Hyprland after you change them.