Shell

• Shell settings
• OSD
• Lock screen
• Keybinds

Shell settings

Section titled “Shell settings”

Global UI settings that apply across all shell surfaces.

[shell]ui_scale = 1.0 # content scale for panels and non-bar shell UIcorner_radius_scale = 1.0 # 0 = square, 1 = default, 2 = extra roundedfont_family = "sans-serif" # Pango family string; Fontconfig handles fallbacklang = "en" # override language detection; BCP-47 or POSIX localetime_format = "{:%H:%M}" # default time format for shell UI without its own settingdate_format = "%A, %x" # default date format for shell UI without its own settingoffline_mode = false # block all outgoing HTTP requestsexternal_ip_enabled = false # resolve and show the WAN IP in the Control Center network tabtelemetry_enabled = false # anonymous startup pingsetup_wizard_enabled = true # open first-run wizard while the marker is missingniri_overview_type_to_launch_enabled = false # niri-only type-to-launch from overviewpolkit_agent = false # register Noctalia's native polkit authentication agentpassword_style = "default" # default | randomavatar_path = "~/Pictures/avatar.png"settings_show_advanced = false # show advanced settings by default in Settingsmiddle_click_opens_widget_settings = true # middle-click bar widgets to open their Settings entryshow_location = true # show weather location text in shell UIlaunch_apps_as_systemd_services = false # launch apps as transient systemd scopeslaunch_apps_custom_command = "" # wrap launched apps; $CMD is replaced with the app commandscreen_time_enabled = false # track per-app usage time for the Control Center screen-time viewapp_icon_colorize = false # recolor application icons across the shellapp_icon_color = "on_surface" # ColorSpec when colorize is enabled; see App icon colorization belowclipboard_enabled = true # false disables clipboard history/panel (basic copy & paste still work)clipboard_history_max_entries = 100 # unpinned history cap (10–10000); pinned entries are exemptclipboard_confirm_clear_history = true # confirm before clear history / delete unpinned entriesclipboard_auto_paste = "auto" # off | auto | ctrl_v | ctrl_shift_v | shift_insertclipboard_image_action_command = "" # image clipboard action; e.g. "gimp {path}" or "satty -f -"shared_gl_context = true # startup-only; share GPU textures across surfacesdisable_mipmaps = false # startup-only; disable texture mipmaps if downscaled icons/wallpaper show GPU artifacts
[shell.animation]enabled = truespeed = 1.0 # 1.0 = normal, 0.5 = 2× slower, 2.0 = 2× faster
[shell.shadow]direction = "down" # center, up, down, left, right, up_left, up_right, down_left, down_rightalpha = 0.55 # multiplied by each component's background opacity
[shell.panel]transparency_mode = "solid" # solid | soft | glass; controls floating/centered opacity and card translucencyborders = true # outline on floating/centered panel shells and section cards inside panelsshadow = true # cast the global [shell.shadow] from panel surfaceslauncher_placement = "centered" # attached | floating | centeredclipboard_placement = "centered" # attached | floating | centeredcontrol_center_placement = "attached" # attached | floating | centeredwallpaper_placement = "attached" # attached | floating | centeredsession_placement = "attached" # attached | floating | centeredpolkit_placement = "floating" # attached | floatingpolkit_position = "center" # auto | center | top_left | … (floating only)floating_offset = 8 # px gap between a floating/detached panel and the bar edgeopen_near_click_control_center = false # attached/floating: follow the bar click instead of bar-centeropen_near_click_launcher = false # attached/floating: follow the bar click instead of bar-centeropen_near_click_clipboard = false # attached/floating: follow the bar click instead of bar-centeropen_near_click_wallpaper = false # attached/floating: follow the bar click instead of bar-centeropen_near_click_session = false # attached/floating: follow the bar click instead of bar-center
[shell.launcher]categories = true # show launcher category filters; Tab toggles them while openshow_icons = true # show application icons in launcher resultscompact = false # smaller icons and tighter rows; hides subtitlesapp_grid = false # icon grid with labels underneath when results are apps onlysession_search = false # include session actions in general search, not only behind /sessionsort_by_usage = true # boost frequently used apps and show Recently Used filter
# Dmenu-style providers: a command emits newline-separated candidates that show up# in the launcher. A tab in a line splits it into title \t description. On activate,# `exec` runs with {selection} substituted; without `exec` the line is copied instead.[shell.launcher.dmenu.entry.ssh]command = "awk '/^Host /{print $2}' ~/.ssh/config" # one candidate per stdout lineexec = "foot ssh {selection}" # {selection} = the chosen line; run detachedprefix = "/ssh" # route behind a prefix; leave empty for global onlyglyph = "server" # optional Tabler glyph shared by every resultglobal = false # true = also surface in unprefixed search
[shell.screen_corners]enabled = false # overlay black rounded corners on each screensize = 32 # corner radius in logical pixels (1–100)
[hot_corners]enabled = false # trigger actions by pushing the mouse pointer into screen cornersdelay_ms = 150 # wait time before triggering to avoid accidental hits
# Configure each corner independently. Available actions:# none | launcher | window-switcher | control-center | command[hot_corners.top_left]action = "none"
[hot_corners.bottom_right]action = "command"command = "swaylock -f"

[shell.mpris]blacklist = [] # optional list of players to hide from media widgets/control-center
[shell.screenshot]save_to_file = true # write captures as PNG to the output directorydirectory = "" # output folder; empty = ~/Picturesfilename_pattern = "screenshot_%Y%m%d_%H%M%S" # strftime pattern, no extension (.png is added)copy_to_clipboard = false # also place the PNG on the clipboard
`avatar_path` controls the avatar Noctalia shows in shell UI such as the Control Center Home tab. When AccountsService is reachable, Noctalia also updates your user's `IconFile` there so other consumers such as Noctalia Greeter can reuse the same avatar. If **accountsservice** is missing or disabled, the shell still uses `avatar_path`, but login greeters that depend on AccountsService will not see that image.freeze_screen = false # freeze the desktop before region selectionconfirm_region = false # confirm region captures with Enter or Spacepipe_to_command = false # pipe the PNG to a shell command on stdinpipe_command = "" # annotator/uploader, e.g. "swappy -f -" or "satty -f -"

Notes:

• ui_scale is completely separate from bar.scale and [widget.*].scale: bar scale settings only affect bar widget content; ui_scale covers the control center, launcher, clipboard, and other non-bar surfaces. Neither changes Wayland output / HiDPI buffer scale.
• font_family sets the primary Pango family for all shell text. Can be a concrete family like Inter or a generic like sans-serif.
• time_format and date_format are fallbacks for shell-owned displays such as the home tab, calendar tab, and lock screen. Widget-specific clock formats still use their own widget settings. See Date format tokens.
• offline_mode prevents the shell from making any outgoing HTTP requests (weather, community palettes, community templates, album art, remote notification icons). Distro packagers can default to true to comply with policies requiring explicit user consent for network access.
• external_ip_enabled: when true, the Control Center network tab resolves the connection’s public WAN IP via api.noctalia.dev/ip and shows it next to the local address. Re-resolves automatically after connection or VPN changes.
• telemetry_enabled sends a single anonymous POST to api.noctalia.dev/ping on each startup containing: a random instance ID, shell version, compositor name, OS name, RAM, monitor resolutions, and UI scale. No personal data is collected. The instance ID is a random UUID stored in ~/.local/state/noctalia/instance.id.
• setup_wizard_enabled: when false, Noctalia does not auto-open the setup wizard on startup even if .setup-complete is missing. Use this for declarative or preseeded deployments; the marker remains the normal completion state for interactive runs.
• niri_overview_type_to_launch_enabled is opt-in. When true on niri, Noctalia keeps a tiny keyboard-focus layer surface while overview is open so typing a letter or number opens the launcher with that initial query. This gives up niri’s exact native handling for some overview-only keyboard state, such as the app focus ring.
• polkit_agent controls registration on org.freedesktop.PolicyKit1. Keep disabled if another desktop agent handles auth prompts. When enabled, shell.panel.polkit_placement and polkit_position control whether the auth prompt attaches to the bar or floats (default: centered on screen).
• Notification daemon ownership moved out of [shell]: use [notification].enable_daemon in Services.
• password_style: default uses circle-filled; random cycles through multiple filled glyph shapes on polkit and lock screen inputs.
• settings_show_advanced: when true, Settings opens with advanced entries visible.
• middle_click_opens_widget_settings: when true, middle-clicking a bar widget opens Settings directly to that widget’s configuration. Set it to false if a plugin widget needs onMiddleClick().
• show_location: when false, weather location text/coordinates are hidden in shell surfaces.
• app_icon_colorize and app_icon_color: global application icon tinting for the dock, system tray (bar and drawer), taskbar, active-window widget, and launcher panel results. See App icon colorization. Bar launcher / control-center widgets can optionally tint custom_image via custom_image_colorize using the widget Color setting (Presentation group in the widget editor).
• lang: empty follows $LC_ALL, $LC_MESSAGES, then $LANG. Values may be BCP-47 tags (pt-BR, zh-Hans) or POSIX locale names (pt_BR.UTF-8, zh_CN.UTF-8). Chinese region locales infer script before matching catalogs, so zh_CN and zh_SG match zh-Hans, while zh_TW, zh_HK, and zh_MO match zh-Hant.
• clipboard_enabled: when false, disables clipboard history only - the history is no longer recorded or persisted, and the clipboard panel and bar/control-center shortcuts are unavailable. The live clipboard transport stays active, so basic copy/cut/paste in text fields and launcher math/emoji copy-to-clipboard actions keep working.
• clipboard_history_max_entries: caps how many unpinned clipboard history rows Noctalia keeps (default 100, range 10–10000). Pinned entries stay outside this limit. Lowering the value trims older unpinned rows on reload.
• clipboard_confirm_clear_history: when true (default), the clipboard panel asks before Clear history and before deleting an unpinned entry (trash in the preview, or double-click a row). When false, those actions apply immediately: sidebar clear removes unpinned rows and keeps pins when any exist, or clears everything when nothing is pinned; unpinned single deletes are immediate. Pinned entries still require confirmation before delete. With confirmation enabled, the clear dialog only offers Keep pinned when both pinned and unpinned rows exist; if history is all pinned or all unpinned, the description matches that case. Toggle in Settings → Shell → Clipboard.
• clipboard_auto_paste: auto = image entries use Ctrl+V, text entries use Ctrl+Shift+V; off = copy only, no automatic paste.
• clipboard_image_action_command: when non-empty, image clipboard previews show an action button. Use {path} to receive an exported image file path. Use {stdin} (expanded to -) or omit {path} to receive the image bytes on stdin, matching the v4 annotation tool behavior (satty -f -, gradia, etc.).
• corner_radius_scale scales rounded corners across shell surfaces: 0 = square, 1 = default, 2 = extra rounded.
• launch_apps_as_systemd_services: when true, apps launched from the launcher, dock, and taskbar run as transient systemd scopes (systemd-run --user --scope) so they survive a shell restart and get their own cgroup.
• launch_apps_custom_command: when non-empty, wraps every app launched from the launcher, dock, and taskbar. The literal $CMD is replaced with the app’s own command - e.g. uwsm-app -- $CMD or gamemoderun $CMD. Mutually exclusive with launch_apps_as_systemd_services; when both are set, the systemd scope wins and the custom command is ignored.
• screen_time_enabled: when true, Noctalia tracks per-app usage time for the Control Center screen-time view and its shortcut. Disabled by default; no usage is recorded while off.
• shared_gl_context: when true (default), all rendering surfaces share a single EGL context group so wallpaper and icon textures are uploaded once in VRAM and reused across monitors. Set to false if you see corrupted textures (e.g. vertical stripe artifacts) on older GPUs with buggy cross-context texture sharing. Each surface then creates its own standalone context, which uses more VRAM on multi-monitor setups. Restart required.
• disable_mipmaps: when true, Noctalia skips mipmap generation for textures. Startup-only - try it if downscaled application icons or wallpapers look blurry or show GPU mipmap artifacts.
• shell.animation.enabled disables all animated transitions globally. speed scales durations globally.
• shell.shadow defines the shared shadow style for shell surfaces and xdg-popup chrome such as panels, menus, pickers, and select dropdowns. direction controls which way the shadow is cast; blur is fixed at 12 px. Components such as panels, bars, and the dock only opt in/out with shadow = true|false.
• shell.panel.transparency_mode controls panel glass styling. solid keeps cards opaque and floating/centered panels solid, soft makes floating/centered panels lightly translucent and cards subtly translucent, and glass makes both visibly translucent while clamping card opacity high enough for readable text. Attached panels continue to use the effective panel background opacity inherited from the host bar.
• shell.panel.borders draws an outline on detached panel shells and on section cards inside panels (control center tabs, clipboard preview, setup wizard steps, etc.). Attached bar-merged panels stay borderless on the shell edge. Default is true; set to false for a flatter, borderless look.
• shell.panel.shadow toggles the rendered drop shadow on attached, floating, and centered panels. Shadow direction and alpha come from [shell.shadow].
• shell.panel.launcher_placement, clipboard_placement, control_center_placement, wallpaper_placement, session_placement, and polkit_placement accept attached or floating. attached merges the panel with the host bar where the bar’s position and placement allow it; floating keeps the panel detached. Defaults are floating for Launcher and Clipboard (with *_position = "center"), attached for Control Center, Wallpaper, and Session, and floating centered for the polkit auth prompt (polkit_placement = "floating", polkit_position = "center").
• Per-panel *_position keys (launcher_position, clipboard_position, control_center_position, wallpaper_position, session_position, polkit_position) apply when placement is floating. auto keeps the panel bar-relative; center and the edge/corner tokens anchor on screen (same vocabulary as notification/OSD position).
• shell.panel.floating_offset sets the gap in pixels between a floating or detached panel and the bar edge (default 8). It applies to floating placement and to panels using the reserved edge area when multiple bars share an edge; attached and centered panels ignore it.
• When multiple enabled bars resolve to the same edge on one monitor, exact source-bar attachment is ambiguous. In that case attached/floating panels use the compositor’s reserved edge area and open outside the bar stack instead of trying to merge with one bar.
• shell.panel.open_near_click_control_center, open_near_click_launcher, open_near_click_clipboard, open_near_click_wallpaper, and open_near_click_session position attached or floating panels near the click location on the bar instead of centering them along the bar. They are ignored when the corresponding placement is centered.
• shell.launcher.categories shows compact category filters in the launcher for providers that expose categories, currently Applications and Emoji. All leaves results unfiltered. With a prefixed provider such as /emo, the filters come from that provider. Press Tab while the launcher is open to hide/show the filters; the left/right keybind actions move between filters.
• shell.launcher.show_icons toggles application icons in launcher result rows. Prefixed-provider rows (for example emoji) still show their leading character when icons are hidden.
• shell.launcher.compact uses smaller icons, tighter padding, and single-line rows (subtitles hidden).
• shell.launcher.app_grid switches to a multi-column icon grid with labels underneath when every visible result is an application. Mixed results (global search, prefixed providers, session actions, and so on) stay in the default list layout.
• shell.launcher.sort_by_usage boosts frequently launched apps toward the top of results and exposes a Recently Used category filter. Disable it for strictly alphabetical ordering within each provider.
• Reset stored launcher usage data from Settings → Panels → Launcher → Reset Usage Data (clears usage_counts.json and recently_used.json while Noctalia is running).
• shell.launcher.session_search surfaces session actions (lock, suspend, reboot, shutdown, logout) in the general launcher search once you type at least two characters, instead of only behind the /session prefix. Disabled by default.
• shell.launcher.dmenu.entry.<id> defines a dmenu-style provider. Each entry runs command (a shell string via /bin/sh -lc) once per launcher session and presents its stdout lines as candidates; a tab in a line splits it into title and description. prefix routes the entry behind a launcher prefix (e.g. /ssh); with no prefix, set global = true or the entry is unreachable. On activate, exec runs detached with {selection} substituted by the chosen line - when exec is omitted the line is copied to the clipboard instead. Entries hot-reload with the config.
• shell.mpris.blacklist excludes matching MPRIS players from Noctalia media UI and active-player selection. Entries are case-insensitive and match player bus name, identity, desktop entry, or a bus-name substring token (for example "spotify").
• shell.screenshot holds the global output policy for all screenshot captures (region, fullscreen), shared by the screenshot bar widget and the screenshot-region / screenshot-fullscreen IPC commands. At least one of save_to_file, copy_to_clipboard, or pipe_to_command must be enabled or the capture reports “No screenshot output enabled”. directory accepts ~; filename_pattern is a strftime pattern (the .png extension is appended). copy_to_clipboard requires clipboard integration (clipboard_enabled = true). pipe_command runs via /bin/sh -lc with the PNG written to its stdin - use it for annotators or uploaders (swappy -f -, satty -f -); for plain clipboard copies use copy_to_clipboard instead. confirm_region keeps the region overlay open after selection until you press Enter or Space (Esc cancels; drag again to reselect). The bar widget itself only configures its glyph and primary_click (region vs fullscreen). On multiple monitors , fullscreen from the bar (or screenshot-fullscreen pick) opens a display picker with one button per connector; scripts can skip the picker with noctalia msg screenshot-fullscreen DP-1 (connector name). Edit in Settings → Shell → Screenshot.
• When pipe_to_command runs, NOCTALIA_SCREENSHOT_PATH is set to the generated PNG path for that capture. If save_to_file = true, Noctalia writes the original PNG there before launching the command; if it is false, the path is still available for commands that need an output target, such as satty -f - -o "$NOCTALIA_SCREENSHOT_PATH".
• Window switcher is an Alt+Tab-style overlay with no [shell] settings yet. Bind your compositor shortcut to noctalia msg window-switcher (see Shell → Window switcher). While open, windows appear in a centered grid (up to five columns) with application icons, titles, and a per-window close control. Tab / Shift+Tab cycle selection; arrow keys move within the grid; releasing Alt or Enter confirms; Escape cancels. The list updates live when windows open, close, or retitle while the overlay stays open.
• Hot corners let you trigger actions by pushing your mouse pointer into one of the four screen corners. When [hot_corners].enabled = true, the shell places invisible 1x1 hit areas in each corner. The pointer must rest in the corner for delay_ms (default 150) before the action triggers. Each corner (top_left, top_right, bottom_left, bottom_right) takes an action. If action is "command", provide a shell command to execute. Configure under Settings → Desktop → Hot Corners.

App icon colorization

Section titled “App icon colorization”

When app_icon_colorize = true, Noctalia recolors application bitmap icons (desktop/tray pixmaps and file-backed icons) so they follow the active palette:

• Dock pinned and running app icons
• Tray inline icons and the tray drawer panel
• Taskbar window icons
• Active window widget icon
• Launcher panel search result app icons (same bake as taskbar)

Glyphs, symbolic tray icons, media album art, and other non-app-bitmap images are unchanged. Launcher panel result icons use the same app-icon bake as the taskbar.

app_icon_color is a color role or fixed hex color (#RGB, #RGBA, #RRGGBB, #RRGGBBAA), using the same picker as bar capsule colors. When omitted while colorize is enabled, Noctalia picks a theme-aware default: on_surface in light mode and on_surface_variant in dark mode.

Icons are desaturated on the CPU, contrast-normalized, then tinted. Changes apply immediately when you edit the setting in Settings → Appearance → Interface , switch light/dark mode, or change the palette.

Per-widget colorize_icons / icon_colorization keys on the dock or tray are no longer used - configure this only under [shell].

OSD

Section titled “OSD”

[osd]position = "top_center" # top_right | top_left | top_center | bottom_right | bottom_left | bottom_center | center_right | center_leftposition_vertical = "top_center" # same options; used when orientation = "vertical"orientation = "horizontal" # horizontal | vertical (volume/brightness sliders only)scale = 1.0 # OSD size multiplier on top of shell.ui_scalebackground_opacity = 0.97 # background opacity of OSD popupsoffset_x = 20 # absolute horizontal margin from the screen edgeoffset_y = 8 # absolute vertical margin from the screen edge# monitors = ["DP-1"] # connector names; omit or leave empty for all monitors
[osd.kinds]volume = true # master volume OSD togglevolume_output = true # output (speaker) volume; requires volume = truevolume_input = true # input (microphone) volume; requires volume = truebrightness = true # display brightnesswifi = true # Wi-Fi togglebluetooth = true # Bluetooth togglepower_profile = true # power profile changescaffeine = true # idle inhibitor togglenightlight = true # night light togglednd = true # Do Not Disturb togglelock_keys = true # Caps/Num/Scroll Lock popupskeyboard_layout = true # input keyboard layout changesprivacy = true # microphone/camera/screen share capture changes

The OSD powers volume, brightness, DND, caffeine, lock-key, keyboard-layout, privacy, external/IPC Wi-Fi, external/IPC Bluetooth, and external/IPC power-profile popups, and defaults to top_center with a horizontal layout. Set orientation = "vertical" for a taller vertical gauge on volume and brightness sliders; text-only popups (media, lock keys, keyboard layout, privacy, and similar) always use horizontal layout for readability. position controls placement for horizontal popups; position_vertical controls placement when slider orientation is vertical. scale multiplies the effective OSD size on top of shell.ui_scale (for example 1.25 makes volume, brightness, and lock-key popups 25% larger than the default). monitors limits OSD popups to the listed connector names (same matching rules as notification toasts and the dock); leave it empty to show on every connected output. If none of the configured monitors are connected, OSD falls back to all outputs until one reconnects. background_opacity sets popup background opacity, and offset_x / offset_y are the absolute margins from the screen edge for the chosen position. Each popup kind can be toggled independently under [osd.kinds]. The volume master toggle enables both output and input OSDs by default; set volume_output or volume_input to false to disable one side only. lock_keys = false disables Caps/Num/Scroll Lock popups; when no lock_keys bar widget is configured, this also stops lock-key state polling. keyboard_layout = false disables layout-change popups. privacy = false disables popups shown when microphone, camera, or screen share capture starts or stops.

Lock screen

Section titled “Lock screen”

Set [lockscreen].enabled = false to turn off session lock entirely: no ext-session-lock-v1 engagement, no logind lock/unlock integration, and lock actions are hidden or no-op (idle lock, session panel, launcher, and noctalia msg session lock). lock-and-suspend falls back to suspend-only while the lock screen is disabled.

When enabled and wlr-screencopy is available, Noctalia can capture the desktop before the session lock engages and use that snapshot as the lock screen background instead of the wallpaper. Desktop capture is disabled by default.

Configure under [lockscreen] in TOML, or use Settings → Security → Lock Screen. The Desktop capture toggle appears only when your compositor supports screencopy. Use Wallpaper to pick a custom lock screen image (empty uses the desktop wallpaper per output).

[lockscreen]enabled = true # master switch for session lockfingerprint = true # allow fingerprint (PAM) authentication on the lock screenallow_empty_password = false # submit Enter with an empty password (security-key PAM stacks)blurred_desktop = false # use a desktop snapshot as the lock screen backgroundblur_intensity = 0.5 # background blur (0.0 = none, 1.0 = maximum)tint_intensity = 0.3 # surface-color tint over the background (0.0 = none, 1.0 = opaque)wallpaper = "" # optional image path; empty uses the desktop wallpaper per outputmonitors = [] # connectors that show the lock screen; empty = all outputs, others stay black

If capture fails (missing protocol, permission denied, etc.), the lock screen falls back to the normal per-output wallpaper. The snapshot lives in memory only until unlock. Blur and tint sliders can be adjusted live from Settings while the session is locked.

Keybinds

Section titled “Keybinds”

Centralized keyboard actions for shell panels (launcher, session, clipboard, wallpaper), panel close/cancel, dismissing interactive region screenshot selection (including while freeze_screen pre-capture is in progress), and keyboard navigation inside Noctalia surfaces such as Settings , Control Center , and the session panel.

[keybinds]validate = ["return", "kp_enter"]cancel = ["escape"]left = ["left"]right = ["right"]up = ["up"]down = ["down"]tab_next = ["tab"]tab_previous = ["shift+tab", "iso_left_tab"]

Each action accepts a single string chord or an array of chords.

Chord format: key, modifier+key, or modifier+modifier+key

Supported modifiers: ctrl, shift, alt

super bindings are rejected (super, win, windows, logo, meta, mod4) and produce a config parse error.

Supported actions: validate, cancel, left, right, up, down, tab_next, tab_previous

On split-pane surfaces ( Settings and Control Center ), tab_next / tab_previous switch between the sidebar and the main content area. Arrow keys stay inside the active pane: the sidebar uses roving focus, and the content area moves between controls on up/down while leaving left/right to control-native behavior (such as slider nudge). The session panel uses arrow keys to move between actions once focus has entered the button list; it does not pre-select an action on open.

Recording from the GUI

Section titled “Recording from the GUI”

Open Settings → Shell → Keybinds to bind chords interactively. Actions are shown in a three-column grid. Each cell lists the current chord(s) for that action plus a trailing “Click to add keybind” slot. When you have not overridden an action in settings.toml, the GUI still shows the built-in defaults (the same chords Noctalia uses at runtime).

• Click a slot (or focus it and press a validate chord) to start recording, then press the key combination. The recorder previews held modifiers (e.g. Ctrl + Shift + …) and commits as soon as a non-modifier key is pressed.
• Press a modifier-only chord (no regular key) and click away to abort the recording without changing the binding.
• Pressing Super / Windows - either alone or as a modifier - cancels the recording and surfaces a transient toast explaining that compositor-reserved keys cannot be bound. Click the slot again to retry with a different chord.
• Use the × next to a row to remove that specific binding. Removing every binding clears the GUI override and restores the built-in default for that action.
• After you change a binding, Override and Reset appear below that action’s list so the title and description keep the full column width.

Chords recorded in the GUI are serialized as ctrl+shift+Return-style strings under [keybinds] in ~/.local/state/noctalia/settings.toml and follow the same parsing rules as hand-written config.

Session panel

Section titled “Session panel”

The session (power) menu opened from the bar Session widget or Control Center lists Lock , Log out , Lock & Suspend , Reboot , and Shut down by default. The launcher also exposes the same enabled entries under /session. noctalia msg session <action> uses the same configured entries (including per-row command overrides and disabled actions). Log out uses compositor-native exits where available, including LabWC’s labwc --exit, unless a row-level command is set. You can change which buttons appear, their order, whether each is enabled, and optionally replace the implementation with a shell command (still run after logging_out / rebooting / shutting_down hooks when the action is one of those three).

Built-in suspend/reboot/shutdown actions resolve from prioritized backend lists (systemd/logind first, then distro/runtime fallbacks) and cache the working backend in-memory for the current session. Override each built-in action globally under [shell.session.power] when auto-detection is not enough:

[shell.session.power]suspend = "sudo -n zzz"reboot = "sudo -n reboot"shutdown = "sudo -n poweroff"

When an override is set, Noctalia runs that command for the built-in suspend/reboot/shutdown actions (session panel, launcher, IPC, idle, and greeter sync). Per-row command still overrides a single menu button when you need one-off behavior (including logout via noctalia msg session logout).

Configure under [shell.session] in TOML, or use Settings → Power → Session menu : entries, reorder, and Show are listed inline; use the settings (cog) control on a row for behavior, label, command, icon, shortcut, countdown, and style. Add action appends a custom-command entry by default. The default five actions are assigned keyboard shortcuts 1 – 5 ; pressing the key while the panel is open triggers the action (or starts its countdown when configured).

Omitting [[shell.session.actions]] entirely keeps the default five actions. To define your own list, declare one or more tables. An explicit empty array hides all session buttons:

[shell.session]grid = falsegrid_columns = 3actions = []
# Example: reorder, disable reboot, custom suspend, override lock[[shell.session.actions]]action = "lock"command = "swaylock -f"
[[shell.session.actions]]action = "logout"enabled = true
[[shell.session.actions]]action = "command"label = "Sleep"glyph = "bedtime"command = "systemctl suspend"
[[shell.session.actions]]action = "shutdown"variant = "destructive"countdown_seconds = 5

Greeter sync

Section titled “Greeter sync”

Settings → Security → Auto-Sync Greeter and Settings → Security → Greeter Sync Privilege Command , or in TOML:

[shell.greeter_sync]auto_sync = trueprivilege_command = "ghostty -e pkexec"

See Noctalia Greeter for seatd and polkit notes.