Skip to Content
Veila
Installation

Build from Source

Compile from a local checkout on Arch, Debian, Ubuntu

Requires Rust 1.89+. Check rustc --version and cargo --version; upgrade with rustup if needed.

On Arch-based systems:

sudo pacman -S --needed rust pkg-config pam wayland libxkbcommon

On Debian/Ubuntu-based systems:

sudo apt install cargo pkg-config libpam0g-dev libwayland-dev libxkbcommon-dev

On NixOS, install with the NixOS module and build with nix develop. The /usr/local steps below are for other distributions.

Build

git clone https://github.com/naurissteins/Veila.git
cd Veila
cargo build --locked --release --workspace

On NixOS, run the build through the checkout’s development shell:

nix develop --command cargo build --locked --release --workspace

The shell supplies pkg-config and native libraries. With direnv and nix-direnv, run direnv allow once to load it automatically.

Nix shell builds use ~/.cache/veila/target/release/veila, unless CARGO_TARGET_DIR overrides the build directory. See NixOS installation for PAM and assets.

On other distributions, the build produces one binary, target/release/veila:

CommandRole
veila lockForeground per-lock supervisor and secure curtain with PAM
veila idleOptional watcher for idle, sleep and logind Lock events
veila status, veila reload, veila theme ...Inspect processes, reload settings and manage themes
veila previewRenders a lockscreen screenshot without locking

Install

Install the binary and bundled themes, fonts, and icons:

sudo install -Dm755 target/release/veila /usr/local/bin/veila
sudo mkdir -p /usr/local/share/veila
sudo cp -R assets/fonts assets/icons assets/themes assets/systemd /usr/local/share/veila/

Before your first lock, install the PAM service for your distribution. On Debian or Ubuntu:

sudo install -Dm644 debian/veila.pam /etc/pam.d/veila

On Arch:

sudo install -Dm644 packaging/arch/veila.pam /etc/pam.d/veila

Then check the selected service:

veila doctor

A missing Veila PAM file triggers a warning and fallback to common-auth or system-auth. Run veila doctor before locking.

Optional: install the man page:

sudo install -Dm644 docs/man/veila.1 /usr/local/share/man/man1/veila.1

For a custom asset directory, set VEILA_ASSET_DIR:

VEILA_ASSET_DIR=/path/to/share/veila veila lock

Release builds prefer installed assets in /usr/local/share/veila or /usr/share/veila, then the source tree. VEILA_ASSET_DIR overrides both.

To install the optional watcher unit on a distribution using systemd:

sudo install -Dm644 assets/systemd/veila.service /usr/lib/systemd/user/veila.service
systemctl --user daemon-reload

First Launch

Lock without a service:

veila lock

Stays in the foreground until unlock.

For keybinds or external idle tools:

veila lock --daemonize --wait-ready

For example, in Hyprland:

bind = SUPER, Escape, exec, veila lock --daemonize --wait-ready

Optional: start the idle/sleep watcher:

systemctl --user enable --now veila.service

Or start veila idle from your compositor. Run one watcher per display. For sweetidle, swayidle, and sleep hooks, see Lock control.

No config is required. Customize the default theme or choose another theme.

On this page