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 windowveila 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 lockValidate before locking:
veila check-configFor a custom path:
veila --config=/path/to/config.toml init --theme default
veila check-config --config=/path/to/config.tomlChecks 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| Key | What it does | Default | Accepted values |
|---|---|---|---|
acquire_timeout_seconds | Confirmation/readiness timeout, plus a 1-second handoff margin. An acquired lock stays protected after timeout. | 5 | integer (min 1) |
auto_reload_config | Automatically reload valid config changes | true | true, false |
auto_reload_debounce_ms | Delay after detecting a change before applying config | 250 | integer ms (effective clamp 250..5000) |
log_to_file | Per-lock supervisor and curtain diagnostics to a file | false | true, false |
log_file_path | Path used when log_to_file = true | - | file path |
auth_backoff_base_ms | Base delay after a failed auth attempt | 750 | integer ms |
auth_backoff_max_seconds | Maximum retry delay cap | 12 | integer seconds |
hide_cursor | Hide the pointer cursor while it is over the lock surface | false | true, false |
allow_empty_password | Submit empty Enter presses to PAM, useful for U2F or fingerprint PAM flows | true | true, false |
screen_off_seconds | Powers displays off while locked | none | integer seconds |
power_off_secondary_outputs | Turn off secondary monitors after readiness in ui_mode = "single" | false | true, false |
suspend_seconds | Suspend system while locked | none | integer seconds |
suspend_only_on_battery | Suspend only when UPower reports that the system is running on battery power. A fully charged laptop on AC stays awake. | false | true, false |
skip_suspend_while_media_playing | Skip suspend on actively playing MPRIS media | false | true, 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| Key | What it does | Default | Accepted values |
|---|---|---|---|
enabled | Start native fprintd verification while locked | false | true, false |
max_failed_attempts | Stop fingerprint scans after this many non-matches in one lock | 5 | integer 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| Key | What it does | Default | Accepted values |
|---|---|---|---|
enabled | Lock after compositor-reported inactivity | false | true, false |
lock_after_seconds | Inactivity time before locking | 300 | 5-86400; values outside the range are clamped and reported by veila check-config |
lock_before_sleep | Attempt to lock before system suspend using a logind delay inhibitor; independent of enabled | true | true, 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 moreRelative 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"| Key | What it does | Default | Accepted values |
|---|---|---|---|
mode | Background source | "gradient" | "file", "gradient", "layered", "radial", "solid" |
path | Wallpaper image path | none | file path |
outputs | Optional per-monitor wallpaper overrides | [] | array of { name, path } entries |
color | Fallback or solid color | "#202833" | any color value |
scaling | Wallpaper scaling per output | "fill" | "fill", "fit", "center", "tile", "stretch" |
gradient | Optional corner colors used when mode = "gradient" | built-in four-corner palette | nested table |
layered | Optional base plus up to three soft blobs used when mode = "layered" | generated base with no blobs | nested table |
radial | Optional colors and position used when mode = "radial" | built-in center/edge palette | nested table |
blur_strength | Wallpaper blur strength for mode = "file" | 0 | 0..255 |
dim_strength | Darkens the wallpaper | 54 | 0..100 percent |
tint | Optional color wash over the background | none | any color value |
slideshow | Optional lock-active wallpaper rotation for mode = "file" | none | nested 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 onlycolor, ignorespath"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 = 128Veila 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 withbackground.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| Key | What it does | Default | Accepted values |
|---|---|---|---|
enabled | Enable module | true | true, false |
directory | Scans for jpg, jpeg, png, and webp | none | directory path |
files | Explicit slideshow image list | [] | array of file paths |
order | Slide traversal order | "sequence" | "sequence", "random" |
mode | Rotating while locked or only change on each new lock. | "timed" | "timed", "lock_only" |
change_every_seconds | How long each slide stays visible while locked when mode = "timed" | 300 | integer 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 = 100Layered
[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 = 50Weather
Enable weather, then style it in Weather visuals.
[weather]
enabled = true
location = "Riga"
refresh_minutes = 15
unit = "celsius"| Key | What it does | Default | Accepted values |
|---|---|---|---|
enabled | Enables weather refresh and the cached widget. | true | true, false |
location | Place name for display and geocoding. | "Riga" | string |
latitude | Explicit latitude in decimal degrees. | none | decimal number |
longitude | Explicit longitude in decimal degrees. | none | decimal number |
refresh_minutes | Weather refresh interval. | 15 | 0..65535 (effective minimum 5) |
unit | Temperature 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| Key | What it does | Default | Accepted values |
|---|---|---|---|
enabled | Enables battery polling. | true | true, false |
refresh_seconds | Polling interval. | 30 | 0..65535 (effective minimum 15) |
mock_percent | Forces a fake battery percentage. | none | 0..100 |
mock_charging | Forces the mock charging state. | none | true, 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"]| Key | What it does | Default | Accepted values |
|---|---|---|---|
include_players | Shows MPRIS players. When empty, all players are eligible | [] | array of strings |
exclude_players | Hides 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.