Skip to Content
Veila
Configuration

General

How to configure Veila using config.toml.

The optional config is ~/.config/veila/config.toml. Without it, Veila uses the packaged theme or built-in defaults.

Create a starter config:

veila init
veila init --theme window

veila init creates a private (0600) config. --force replaces an existing file and preserves its permissions.

Use --config for a custom path:

veila lock --config=/path/to/config.toml
veila lock

Validate before locking:

veila check-config

For a custom path:

veila --config=/path/to/config.toml init --theme default
veila check-config --config=/path/to/config.toml

Checks syntax, values, colors, and unknown keys across config, themes, and includes. Errors return a non-zero exit code.

Color Values

Color fields accept these formats:

color = "#202833"            # hex RGB
color = "#202833CC"          # hex RGBA (last two digits = alpha)
color = "rgb(32, 40, 51)"
color = "rgba(32, 40, 51, 0.8)"

Lock

Set authentication retry delays, display power, suspend, and reload behavior.

[lock]
acquire_timeout_seconds = 5
auto_reload_config = true
auto_reload_debounce_ms = 250
log_to_file = false
log_file_path = "~/.local/state/veila/veila.log"
auth_backoff_base_ms = 750
auth_backoff_max_seconds = 12
hide_cursor = false
allow_empty_password = true
screen_off_seconds = 10
power_off_secondary_outputs = false
suspend_seconds = 300
suspend_only_on_battery = false
skip_suspend_while_media_playing = false
KeyWhat it doesDefaultAccepted values
acquire_timeout_secondsConfirmation/readiness timeout, plus a 1-second handoff margin. An acquired lock stays protected after timeout.5integer (min 1)
auto_reload_configAutomatically reload valid config changestruetrue, false
auto_reload_debounce_msDelay after detecting a change before applying config250integer ms (effective clamp 250..5000)
log_to_filePer-lock supervisor and curtain diagnostics to a filefalsetrue, false
log_file_pathPath used when log_to_file = true-file path
auth_backoff_base_msBase delay after a failed auth attempt750integer ms
auth_backoff_max_secondsMaximum retry delay cap12integer seconds
hide_cursorHide the pointer cursor while it is over the lock surfacefalsetrue, false
allow_empty_passwordSubmit empty Enter presses to PAM, useful for U2F or fingerprint PAM flowstruetrue, false
screen_off_secondsPowers displays off while lockednoneinteger seconds
power_off_secondary_outputsTurn off secondary monitors after readiness in ui_mode = "single"falsetrue, false
suspend_secondsSuspend system while lockednoneinteger seconds
suspend_only_on_batterySuspend only when UPower reports that the system is running on battery power. A fully charged laptop on AC stays awake.falsetrue, false
skip_suspend_while_media_playingSkip suspend on actively playing MPRIS mediafalsetrue, false

suspend_seconds works independently of screen_off_seconds. Other power managers may conflict with Veila’s logind suspend requests. Keyboard and button presses postpone suspend.

power_off_secondary_outputs requires [visuals.outputs].ui_mode = "single" and compositor power-management support. Every output is locked before secondary monitors turn off.

Changes are checked every second by the watcher or every 250 ms while locked, then debounced. Use veila reload to request an immediate reload. Without a running process, edits apply on the next lock.

Invalid reloads keep the last valid settings. Auto reload watches the config, theme, includes, and wallpaper.

veila logs reads the optional lock file and watcher journal. Use --file or --journal --idle to select one. Enable file logging with log_to_file.

Caches and logs use private permissions (0700 directories, 0600 files), tightened at startup. Logs rotate at 8 MiB with three backups; veila logs --file --follow follows rotation.

Fingerprint

Enable experimental fingerprint verification through fprintd.

[fingerprint]
enabled = false
max_failed_attempts = 5
KeyWhat it doesDefaultAccepted values
enabledStart native fprintd verification while lockedfalsetrue, false
max_failed_attemptsStop fingerprint scans after this many non-matches in one lock5integer 1..255

Scan any enrolled finger to unlock. Password input remains available if the reader or fprintd fails.

Scans pause before suspend and restart after resume. Temporary failures retry with backoff; non-matches accumulate until the next lock. At the limit, use your password.

Idle

These settings require veila idle or veila.service. They do not control manual locks or external idle tools.

[idle]
enabled = false
lock_after_seconds = 300
lock_before_sleep = true
KeyWhat it doesDefaultAccepted values
enabledLock after compositor-reported inactivityfalsetrue, false
lock_after_secondsInactivity time before locking3005-86400; values outside the range are clamped and reported by veila check-config
lock_before_sleepAttempt to lock before system suspend using a logind delay inhibitor; independent of enabledtruetrue, false

Idle locking requires ext-idle-notify-v1; check support with veila doctor. Changes apply live. See Lock Control for use with hypridle or swayidle.

Include Files

Load extra TOML files with include. Use this for colors generated by matugen, cwal, wallust, or pywal.

include = ["~/.cache/matugen/veila.toml"]

theme = "default"

[background]
mode = "file"
path = "/home/user/Pictures/wallpaper.jpg"

The included file can contain normal config sections:

[background]
color = ""

[visuals.clock]
color = ""

[visuals.input]
background_color = ""
border_color = ""
# and more

Relative includes resolve beside the config. Includes, wallpapers, and slideshows expand ~ from $HOME; ~user stays literal. Without HOME, ~ also stays literal.

The main config overrides includes. Missing includes are skipped; invalid TOML keeps the last valid config on reload.

Includes cannot load more files or select themes. Their theme and include keys are ignored.

Background

Choose a wallpaper or generated background. Setting path selects file mode unless another mode is explicit.

[background]
mode = "gradient"
color = "#202833"
scaling = "fill"
dim_strength = 54

[background.gradient]
top_left = "#A85BFF"
top_right = "#39B8FF"
bottom_left = "#6FE2FF"
bottom_right = "#6F4CFF"

[[background.outputs]]
name = "DP-1"
path = "/path/to/left.jpg"

[[background.outputs]]
name = "HDMI-A-1"
path = "/path/to/right.jpg"
KeyWhat it doesDefaultAccepted values
modeBackground source"gradient""file", "gradient", "layered", "radial", "solid"
pathWallpaper image pathnonefile path
outputsOptional per-monitor wallpaper overrides[]array of { name, path } entries
colorFallback or solid color"#202833"any color value
scalingWallpaper scaling per output"fill""fill", "fit", "center", "tile", "stretch"
gradientOptional corner colors used when mode = "gradient"built-in four-corner palettenested table
layeredOptional base plus up to three soft blobs used when mode = "layered"generated base with no blobsnested table
radialOptional colors and position used when mode = "radial"built-in center/edge palettenested table
blur_strengthWallpaper blur strength for mode = "file"00..255
dim_strengthDarkens the wallpaper540..100 percent
tintOptional color wash over the backgroundnoneany color value
slideshowOptional lock-active wallpaper rotation for mode = "file"nonenested table
  • "gradient" - generate four-corner gradient using [background.gradient]
  • "layered" - generate base plus up to three soft blobs using [background.layered]
  • "radial" - generate radial bloom using [background.radial]
  • "solid" - renders only color, ignores path
  • "file" - scales the image per output with blur, dim, and tint applied

For wallpapers, 0 disables blur, 12 gives a soft blur, and 64–255 soften broad shapes. Try 128 for strong blur. Generated backgrounds ignore this setting.

For a strong wallpaper blur:

[background]
mode = "file"
path = "/path/to/wallpaper.jpg"
blur_strength = 128

Veila shows a secure curtain first, using background.color for file wallpapers. It reads cached wallpapers while the lock starts so the image can appear with the password prompt. If the image is still loading, the prompt appears over the fallback color. Choose a color close to the wallpaper after dimming and tinting to make that transition less visible. Veila manages the cache automatically.

For translucent tint, use rgba(...) or #RRGGBBAA.

For mode = "file":

  • "fill" covers the full output and crops overflow
  • "fit" keeps the whole image visible and fills bars with background.color
  • "center" keeps the original image size, centered, and clips only if it is larger than the output
  • "tile" repeats the image across the full output
  • "stretch" scales the image to the output size without preserving aspect ratio

background.color fills transparent pixels and space around centered images. Reloading updates cached wallpapers too.

Per-monitor

Use compositor output names for per-monitor wallpapers. Blur, dim, tint, and fallback settings come from [background].

[background]
mode = "file"
path = "/path/to/default.jpg"

[[background.outputs]]
name = "DP-1"
path = "/path/to/left.jpg"

[[background.outputs]]
name = "HDMI-A-1"
path = "/path/to/right.jpg"

Unmatched outputs use [background]; failed images use a fallback and keep the output locked.

Large per-monitor images can increase loading time and memory use, especially with an empty cache.

Slideshow

Use timed to cycle wallpapers while locked, or lock_only to choose one per lock.

[background.slideshow]
enabled = true
directory = "~/Pictures/Wallpapers"
mode = "timed"

# files = [
#   "~/Pictures/Wallpapers/01.jpg",
#   "~/Pictures/Wallpapers/02.jpg"
# ]

order = "random"
change_every_seconds = 60
KeyWhat it doesDefaultAccepted values
enabledEnable moduletruetrue, false
directoryScans for jpg, jpeg, png, and webpnonedirectory path
filesExplicit slideshow image list[]array of file paths
orderSlide traversal order"sequence""sequence", "random"
modeRotating while locked or only change on each new lock."timed""timed", "lock_only"
change_every_secondsHow long each slide stays visible while locked when mode = "timed"300integer seconds (min 1)

Generated Colors

Generate a background without an image. See Color backgrounds for examples.

Gradient

[background]
mode = "gradient"
blur_strength = 0
dim_strength = 0

[background.gradient]
top_left = "#A85BFF"
top_right = "#39B8FF"
bottom_left = "#6FE2FF"
bottom_right = "#6F4CFF"

Radial

[background]
mode = "radial"
blur_strength = 0
dim_strength = 0

[background.radial]
center = "#6FE2FF"
edge = "#6F4CFF"
center_x = 50
center_y = 50
radius = 100

Layered

[background]
mode = "layered"
blur_strength = 0
dim_strength = 0

[background.layered.base]
mode = "gradient"

[background.layered.base.gradient]
top_left = "#A85BFF"
top_right = "#39B8FF"
bottom_left = "#6FE2FF"
bottom_right = "#6F4CFF"

[[background.layered.blobs]]
color = "#FFFFFF"
opacity = 16
x = 18
y = 12
size = 42

[[background.layered.blobs]]
color = "#7C4DFF"
opacity = 22
x = 82
y = 78
size = 50

Weather

Enable weather, then style it in Weather visuals.

[weather]
enabled = true
location = "Riga"
refresh_minutes = 15
unit = "celsius"
KeyWhat it doesDefaultAccepted values
enabledEnables weather refresh and the cached widget.truetrue, false
locationPlace name for display and geocoding."Riga"string
latitudeExplicit latitude in decimal degrees.nonedecimal number
longitudeExplicit longitude in decimal degrees.nonedecimal number
refresh_minutesWeather refresh interval.150..65535 (effective minimum 5)
unitTemperature unit."celsius""celsius", "fahrenheit"

Set both coordinates to skip location lookup.

Battery

Set the battery update interval or use mock values for screenshots.

[battery]
enabled = true
refresh_seconds = 30
KeyWhat it doesDefaultAccepted values
enabledEnables battery polling.truetrue, false
refresh_secondsPolling interval.300..65535 (effective minimum 15)
mock_percentForces a fake battery percentage.none0..100
mock_chargingForces the mock charging state.nonetrue, false

Without a battery, the widget stays hidden unless mock_percent is set.

Now Playing

Filter media players here; style the widget in Now Playing visuals.

[now_playing]
include_players = ["Spotify", "mpv"]
exclude_players = ["Firefox", "Chromium"]
KeyWhat it doesDefaultAccepted values
include_playersShows MPRIS players. When empty, all players are eligible[]array of strings
exclude_playersHides matching MPRIS players from the now-playing[]array of strings

Titles and artist names are limited to 256 characters. Artwork URLs over 4096 bytes are ignored.

On this page