Skip to Content
Veila
Configuration

Lock Control

Manual lock commands and the wait-ready mode for scripts and automation

For normal locking:

veila lock

veila 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-ready

The command waits for compositor confirmation and UI readiness on every output, then prints:

lock_ready=true
already_active=false

Duplicate 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.service

Stopping 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 = true
  • enabled: lock after lock_after_seconds. Requires ext-idle-notify-v1 and 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-ready

Latency report

To inspect lock activation timing, run:

veila lock --latency-report --wait-ready

The 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-ready

Verbose mode adds microsecond timings and gaps between startup stages.

On this page