v5-services-idle.md
Idle behaviors are named entries under [idle.behavior.*]. When the resolved config does not define idle behaviors, Noctalia seeds built-in Lock and Monitor off behaviors, both disabled by default.
Optional top-level [idle] keys apply before any behavior’s command runs:
[idle]# Seconds to fade a fullscreen surface-tint overlay, then run the idle command.# 0 disables the overlay (the command runs as soon as the compositor reports idle).# Parsed between 0 and 120; the in-app Settings stepper uses whole seconds 0–30.pre_action_fade_seconds = 2.0
While a fade is in progress, the overlay is click-through so pointer/keyboard activity still reaches the compositor; if the session becomes active again during that window, the pending command is cancelled. The dim is a layer-shell overlay that covers the full monitor (including the bar).
Each behavior picks an action. The built-in actions are native - they need no command. Use action = "command" only when you want to run something Noctalia doesn’t have a native action for (a shell command, or an internal noctalia: command).
[idle.behavior.lock]timeout = 600action = "lock"enabled = false # explicitly disabled in the default config
[idle.behavior.screen-off]timeout = 660action = "screen_off" # turns monitors off, and back on when you returnenabled = false # explicitly disabled in the default config
[idle.behavior.suspend]timeout = 900action = "lock_and_suspend" # or action = "suspend" with lock_before_suspend = false
[idle.behavior.custom]timeout = 48action = "command"command = "notify-send 'Idle' 'Going idle'"resume_command = "notify-send 'Idle' 'Back from idle'"
| Setting | Type | Default | Description |
|---|---|---|---|
action | string | "command" | What the behavior does: lock, screen_off, suspend, lock_and_suspend, or command |
enabled | bool | true | Enable or disable this behavior |
timeout | number | 0 | Seconds before the behavior triggers; fractional values are allowed (e.g. 0.3); 0 disables this behavior |
command | string | "" | Only for action = "command": a shell command or noctalia: IPC subcommand to run when idle |
resume_command | string | "" | Only for action = "command": a shell command or noctalia: IPC subcommand to run when activity resumes |
lock_before_suspend | bool | true | For action = "suspend", lock the session first (equivalent to action = "lock_and_suspend"). Set false to suspend without locking. |
action = "screen_off" turns the monitors off on idle and back on automatically when you return - no command/resume_command needed. (This automatic monitor-on resume applies only to the native screen_off action; a custom action = "command" that powers monitors off must set its own resume_command to turn them back on.)
noctalia: commands (action = "command")Section titled “noctalia: commands (action = "command")”
For action = "command", the noctalia: prefix runs the rest of the string through the IPC command registry - the same as noctalia msg <subcommand> - so a behavior can trigger any internal action. Examples:
noctalia:session locknoctalia:session suspendnoctalia:session lock-and-suspendnoctalia:dpms-offnoctalia:dpms-onnoctalia:caffeine-enablenoctalia:caffeine-disablenoctalia:caffeine-togglenoctalia:panel-open launchernoctalia:panel-closenoctalia:panel-toggle launchernoctalia:panel-toggle sessionnoctalia:panel-toggle clipboardnoctalia:panel-toggle wallpapernoctalia:panel-toggle control-centernoctalia:media previousnoctalia:media togglenoctalia:media stopnoctalia:media next
media stop pauses the active player (falling back to the MPRIS Stop method for players that do not support pause) and is a no-op when nothing is playing. Unlike media toggle, which flips between play and pause, media stop only ever stops playback and never resumes it.
Idle behavior uses the Wayland ext_idle_notifier_v1 protocol and respects active idle inhibitors.
The examples above use commands from these canonical IPC references:
dpms-on / dpms-off)