Skip to content
Noctalia Noctalia
FAQ

Shell

Shell

Section titled “Shell”

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 UI
font_family           = "sans-serif"    # Pango family string; Fontconfig handles fallback
lang                  = "en"            # override language detection
time_format           = "{:%H:%M}"      # default time format for shell UI without its own setting
date_format           = "%A, %x"        # default date format for shell UI without its own setting
offline_mode          = false           # block all outgoing HTTP requests
telemetry_enabled     = false           # anonymous startup ping
polkit_agent          = false           # register Noctalia's native polkit authentication agent
password_style        = "default"       # default | random
avatar_path           = "~/Pictures/avatar.png"
settings_show_advanced = false          # show advanced settings by default in Settings
middle_click_opens_widget_settings = true # middle-click bar widgets to open their Settings entry
show_location         = true            # show weather location text in shell UI
clipboard_auto_paste  = "auto"          # off | auto | ctrl_v | ctrl_shift_v | shift_insert
clipboard_image_action_command = ""     # image clipboard action; e.g. "gimp {path}" or "satty -f -"


[shell.animation]
enabled = true
speed   = 1.0   # 1.0 = normal, 0.5 = 2× slower, 2.0 = 2× faster


[shell.shadow]
blur     = 12    # global surface shadow blur radius; 0 disables all rendered surface shadows
offset_x = 2
offset_y = 2     # positive = down
alpha    = 0.55  # multiplied by each component's background opacity


[shell.panel]
background_blur       = true   # request compositor blur behind panels via ext-background-effect-v1
attach_launcher       = false  # attach launcher to the bar when a suitable bar is available
attach_clipboard      = false  # attach clipboard history to the bar when a suitable bar is available
attach_control_center = true   # attach Control Center to the bar when a suitable bar is available
attach_wallpaper      = true   # attach wallpaper picker to the bar when a suitable bar is available


[shell.screen_corners]
enabled = false    # overlay black rounded corners on each screen
size    = 32       # corner radius in logical pixels (1–100)


[shell.mpris]
blacklist = []           # optional list of players to hide from media widgets/control-center

Notes:

  • ui_scale is completely separate from bar.scale: bar.scale only affects 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.
  • 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.
  • polkit_agent controls registration on org.freedesktop.PolicyKit1. Keep disabled if another desktop agent handles auth prompts.
  • 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 scripted widget needs onMiddleClick().
  • show_location: when false, weather location text/coordinates are hidden in shell surfaces.
  • 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.).
  • shell.animation.enabled disables all animated transitions globally. speed scales durations globally.
  • shell.shadow defines the shared shadow metrics for shell surfaces. Components such as bars and the dock only opt in/out with shadow = true|false; they do not define their own blur or offset.
  • shell.panel.background_blur toggles compositor blur on every shell panel (control center, launcher, clipboard, attached menus, etc.). Inert on compositors that do not implement ext-background-effect-v1.
  • shell.panel.attach_launcher, attach_clipboard, attach_control_center, and attach_wallpaper control whether those panels attach to the bar when a suitable bar is available. Attachment still requires the host bar to have attach_panels = true.
  • 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").

OSD

Section titled “OSD”
[osd]
position = "top_right"   # top_right | top_left | top_center | bottom_right | bottom_left | bottom_center

The OSD powers the volume HUD and defaults to top_right.

Keybinds

Section titled “Keybinds”

Centralized keyboard actions for shell panels (launcher, session, clipboard, wallpaper) and panel close/cancel.

[keybinds]
validate = ["return", "kp_enter"]
cancel   = ["escape"]
left     = ["left"]
right    = ["right"]
up       = ["up"]
down     = ["down"]

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

Session panel

Section titled “Session panel”

The session (power) menu opened from the bar Session widget or Control Center lists Lock, Log out, Reboot, and Shut down by default. 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).

Configure under [shell.session] in TOML, or use Settings → Panels → Session menu: entries, reorder, and Show are listed inline; use the settings (cog) control on a row for behavior, label, command, icon, and style. Add action appends a custom-command entry by default.

FieldTypeDefaultDescription
actionstringrequiredlock, logout, reboot, shutdown, or command (custom entry).
enabledbooltrueWhen false, the button is hidden.
commandstringunsetOptional. If set, the string is run with /bin/sh -c instead of the built-in handler. For action = "command", this field is required.
labelstringunsetOptional button label (otherwise translated defaults).
glyphstringunsetOptional bar-style icon id (otherwise defaults per action). Under Session menu in Settings → Panels, open a row’s settings (cog) editor and use the icon preview to pick a glyph.
destructiveboolfalseUse the destructive (warning) button style.

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

[shell.session]
actions = []


# 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"
destructive = true

Hooks

Section titled “Hooks”

Optional shell hooks run extra commands when specific events happen. Define them under [hooks] in config.toml. Each event is a string (one command) or an array of strings (run in order). The same noctalia: prefix rules apply as in idle behaviors.

Hooks do not replace Noctalia’s built-in behavior. For example, Wi-Fi and Bluetooth power changes made outside Noctalia still create internal Noctalia notifications even when wifi_* / bluetooth_* hooks are not configured. notify-send can be useful while testing that a hook fires, but it is not required for Noctalia’s own notifications.

KeyWhen it fires
startedOnce after Noctalia finishes startup (IPC ready).
wallpaper_changedAfter a persisted wallpaper path change is applied.
colors_changedAfter the theme palette is resolved and terminal templates are updated.
session_lockedWhen the compositor confirms the session lock.
session_unlockedWhen the session leaves the locked state.
logging_outImmediately before the session panel runs the logout sequence.
rebootingImmediately before the session panel runs reboot.
shutting_downImmediately before the session panel runs shutdown.
wifi_enabled / wifi_disabledWhen NetworkManager’s Wi-Fi radio toggles (not on first snapshot).
bluetooth_enabled / bluetooth_disabledWhen the default adapter’s powered state toggles (not on first snapshot).
battery_state_changedWhen UPower’s battery state enum changes (charging, discharging, etc.). Sets NOCTALIA_BATTERY_STATE (e.g. Charging, Discharging, Charged).
battery_under_thresholdWhen charge crosses from above to at or below battery_low_percent_threshold. Sets NOCTALIA_BATTERY_PERCENT.
SettingTypeDefaultDescription
battery_low_percent_thresholdint0Percent (0–100). 0 disables battery_under_threshold. Set to e.g. 15 to activate.
[hooks]
# Start a user unit after Noctalia IPC is ready.
started = "systemctl --user start noctalia-ready.target"


# Reload tools that consume generated wallpaper/theme files.
wallpaper_changed = "systemctl --user restart wallpaper-sync.service"
colors_changed = [
  "systemctl --user reload foot-server.service",
  "logger -t noctalia-hooks 'palette colors changed'",
]


# Combine normal shell commands with Noctalia IPC commands.
session_locked = [
  "playerctl pause",
  "noctalia:bar-hide",
]
session_unlocked = [
  "noctalia:bar-show",
  "noctalia:dpms-on",
]


logging_out   = "logger -t noctalia-hooks 'logout requested'"
rebooting     = "systemctl --user stop backup-sync.service"
shutting_down = "systemctl --user stop backup-sync.service"


# External Wi-Fi/Bluetooth power changes emit internal notifications without these hooks;
# use hooks only for extra side effects. Changes made from Noctalia do not toast.
wifi_enabled  = "logger -t noctalia-hooks 'Wi-Fi radio enabled'"
wifi_disabled = "logger -t noctalia-hooks 'Wi-Fi radio disabled'"


bluetooth_enabled  = "logger -t noctalia-hooks 'Bluetooth powered on'"
bluetooth_disabled = "logger -t noctalia-hooks 'Bluetooth powered off'"


battery_low_percent_threshold = 15
battery_state_changed   = "logger -t noctalia-hooks \"Battery: $NOCTALIA_BATTERY_STATE\""
battery_under_threshold = "systemctl --user start battery-low.target"


# Quick test while developing a hook; not needed for Noctalia's own notifications.
# started = "notify-send 'Noctalia hook' 'started fired'"