Lock Control
Manual lock commands and the wait-ready mode for scripts and automation
For normal locking:
veila lockveila lock stays in the foreground until unlock. No background service is required; password authentication survives a supervisor exit.
For keybinds and scripts that must return after the lock is ready:
veila lock --daemonize --wait-readyThe command waits for compositor confirmation and UI readiness on every output, then prints:
lock_ready=true
already_active=falseDuplicate requests reuse the active lock and report already_active=true. --wait-ready fails if that lock ends or its supervisor exits before reporting UI readiness. It never starts a second lock.
--daemonize alone waits only for compositor confirmation. A late UI or failed readiness check leaves an acquired lock protected, with password authentication available.
veila status shows the lock and watcher state. veila reload requests a reload; invalid edits keep the last valid config. With no live process, edits apply on the next lock. Run both commands in your desktop’s WAYLAND_DISPLAY and XDG_RUNTIME_DIR.
Stopping or restarting the watcher
veila.service runs the optional idle, sleep, and logind Lock watcher. To restart it:
systemctl --user restart veila.serviceStopping or restarting the watcher preserves an active lock and password entry. Use veila status or veila doctor; veila stop and veila health were removed.
veila daemon and veilad are deprecated aliases for veila idle. Replace them in launchers and configure timeouts in [idle]; veila-idle.service and the old timeout flags are obsolete.
Password prompts
PAM may request extra responses, such as one-time codes. Hidden responses stay masked; visible prompts show what you type. Press Enter to submit or Escape to cancel.
Attempts time out after 30 seconds, or 120 seconds for interactive authentication with 60 seconds per prompt. Failure, cancellation, and timeout keep the session locked and apply the retry delay.
Input is limited to 128 characters. Extra characters are ignored with a “Maximum 128 characters” message. Backspace clears it.
hypridle example
general {
lock_cmd = veila lock --daemonize --wait-ready # veila screen lock
before_sleep_cmd = veila lock --daemonize --wait-ready # lock before suspend
after_sleep_cmd = hyprctl dispatch dpms on # wake display after sleep
inhibit_sleep = 3
}
# Dim the screen first (optional)
listener {
timeout = 150 # 2.5 minutes
on-timeout = brightnessctl -s set 10% # set monitor backlight to 10%
on-resume = brightnessctl -r # restore monitor backlight
}
# Lock the screen (Visible)
listener {
timeout = 300 # 5 minutes
on-timeout = veila lock --daemonize --wait-ready # lock screen (stays visible)
}
# Turn off the screen (Black out)
listener {
timeout = 600 # 10 minutes (5 mins after locking)
on-timeout = hyprctl dispatch dpms off # turn off display
on-resume = hyprctl dispatch dpms on # turn on display
}External idle tools
Use veila lock --daemonize --wait-ready as the lock command in sweetidle, swayidle or a compositor keybind. For swayidle, an example is:
swayidle -w \
timeout 300 'veila lock --daemonize --wait-ready' \
before-sleep 'veila lock --daemonize --wait-ready'Configure sleep inhibition in your idle tool. [idle] applies only to veila idle. loginctl lock-session needs the Veila watcher or another listener to start locking.
Built-in idle and sleep locking
Configure the optional idle watcher in config.toml:
[idle]
enabled = true
lock_after_seconds = 300
lock_before_sleep = trueenabled: lock afterlock_after_seconds. Requiresext-idle-notify-v1and respects idle inhibitors.lock_before_sleep: enabled by default, independently of idle locking. Delays suspend while acquiring the lock. Failure or logind’s deadline can allow suspend without a lock; check the watcher journal.
Changes apply through auto reload or veila reload. See Idle settings for defaults.
Run veila idle --config=/path/to/config.toml or enable veila.service, with one watcher per display. It handles idle, sleep, and this session’s logind Lock signal. Config reload follows lock.auto_reload_config; veila reload or SIGHUP forces a reload. See veila idle --help for options.
Emergency unlock prompt
If the scene fails, a minimal prompt keeps the same secure surfaces and PAM authentication.
To test it:
veila lock --force-emergency-ui --wait-readyLatency report
To inspect lock activation timing, run:
veila lock --latency-report --wait-readyThe report covers startup through lock readiness and contains no authentication secrets. Update older scripts: daemon_config_load_* is now config_load_*, and daemon_socket_setup_* is now control_channel_setup_* (both ms and us). Other keys are unchanged.
For deeper local profiling, use:
veila lock --latency-report=verbose --wait-readyVerbose mode adds microsecond timings and gaps between startup stages.