// reference

Configuration

Everything boot.conf understands.

Config lives at \EFI\visor\boot.conf on the ESP. A fully-commented reference ships as boot.conf.example. Two rules apply everywhere:

• Paths are relative to the root of the filesystem containing the file and use backslashes. Assets normally live on the ESP, for example \EFI\visor\icons\arch.png. On a separate /boot filesystem use \vmlinuz-...; use \boot\vmlinuz-... only when /boot is a directory inside the root filesystem.
• Colors are #RRGGBB.

No boot.conf at all is a supported configuration — Visor auto-detects entries (see Features). Validate a config from Linux with visor config validate.

Kernels and initrds on non-FAT partitions (btrfs, ext4, etc.) need an efifs driver in \EFI\visor\drivers\. A UKI on the ESP under \EFI\Linux\*.efi always works without a driver.

Global settings

Logo

An image drawn in the header, next to the title or on its own. The bundled Visor logo (\EFI\visor\logo.png) is used by default. PNG or BMP; transparency is respected, and a square image looks best (it is scaled to a square).

Colors

Blur highlight

Replace the flat selection card with a blurred-glass panel that follows the selection (entries and power actions), with softly feathered edges.

Animation

Font sizes

Icons

All values in pixels. 0 or absent = sensible default.

Selection underline

The accent bar under the selected entry.

Power actions

Shutdown, Reboot, and Firmware setup actions, accessible via the S / R / F keys and optionally a corner icon stack.

Background

Dynamic accent

Derive a Material You palette from the background image and apply it to the UI — the same pipeline the caelestia shell uses for the desktop. The wallpaper is quantized (Wu box-cut, 128 colors), a seed color is picked with Material's Score algorithm, and the full set of Material dynamic-color roles is generated for a dark scheme:

• primary → selection underline + highlight
• secondary → shutdown / reboot power actions
• tertiary → firmware power action
• onSurface → entry names (when accent_text=1)
• onSurfaceVariant → countdown, hints, dim labels
• surface → fallback background tint; onPrimaryContainer frost tint

Needs a background image; with a solid backdrop it does nothing and the configured colors are kept.

Any color set explicitly (e.g. underline_color, name_color) is overridden by the accent for whichever roles are enabled above.

Themes

A theme is a .conf file in \EFI\visor\themes\ containing any of the UI keys above (colors, sizes, icons, underline, power, background, title, logo, …). Its values override boot.conf. Boot entries always stay in boot.conf — themes are UI-only.

Snapshots

Visor supports booting into btrfs snapshots from two sources, in priority order:

1. Manifest (recommended): A Linux-side hook mirrors the snapshot list to the ESP at \EFI\visor\snapshots.conf. Visor also falls back to \EFI\visor\snapshot.conf (singular) if the plural file is absent — check the boot log to see which name was loaded. See tools/visor-snapshot-sync; run it from a pacman hook or a systemd path unit watching /.snapshots. Works on any firmware, exact cmdlines from the running system.
2. Auto-detect (zero-config fallback): When no manifest exists and a btrfs EFI driver is loaded, Visor detects snapshots itself — snapper, Timeshift (btrfs mode), or plain subvolume layouts under /.snapshots. Needs exactly one Linux entry with a root= cmdline; shows the newest 12 snapshots, booted with the entry's current kernel.

Manifest entries use a snapshot { } block:

snapshot {
    os      = Arch Linux         # boot entry to attach to (name substring)
    id      = 42
    date    = 2026-07-18 14:22
    desc    = pacman -Syu linux
    cmdline = root=UUID=... rootflags=subvol=@/.snapshots/42/snapshot ro
}

In the menu, press V on an entry to cycle its bottom panel: entry info → deployments (BLS / ostree) → snapshots → back. Up / Down or the mouse wheel select; Enter boots the selected snapshot (one-shot); Esc backs out.

Boot entries

Visor auto-detects how to boot each entry from the image itself:

• A PE image with no initrd/cmdline → chainloaded (Windows bootmgfw.efi, GRUB, shim). Loaded by device path so the loader finds its own files.
• A PE image (UKI or EFI-stub vmlinuz) → LoadImage / StartImage, with cmdline and initrd applied via the standard LINUX_EFI_INITRD_MEDIA_GUID protocol.
• A raw (non-PE) kernel → Linux EFI handover boot-params path.

There is no separate linux / windows block type or a type= key — everything is entry { }. The old block names are still accepted as aliases so existing configs keep working.

entry {
    name    = "Arch Linux"
    icon    = \EFI\visor\icons\arch.png
    color   = #1793D1
    kernel  = \vmlinuz-linux
    initrd  = \initramfs-linux.img
    cmdline = "root=PARTUUID=... rw quiet"
}

entry {
    name   = "Windows 11"
    icon   = \EFI\visor\icons\windows.png
    kernel = \EFI\Microsoft\Boot\bootmgfw.efi
}

Encrypted entry example

entry {
    name      = "Encrypted Arch"
    icon      = \EFI\visor\icons\arch.png
    kernel    = \vmlinuz-linux.venc
    initrd    = \initramfs-linux.img.venc
    encrypted = 1
    cmdline   = "root=PARTUUID=... rw quiet"
}

LUKS entry example

entry {
    name      = "Arch LUKS"
    icon      = \EFI\visor\icons\arch.png
    kernel    = \vmlinuz-linux
    initrd    = \initramfs-linux.img
    cmdline   = "rd.luks.name=12345678-1234-1234-1234-123456789abc=cryptroot root=/dev/mapper/cryptroot rw quiet"
    luks      = 1
    luks_key_path = /crypto_keyfile.bin
    luks_preset = mkinitcpio
    # For custom initramfs setups, use luks_cmdline instead.
}

UKI + LUKS example

The UKI is left unchanged; Visor provides a supplemental keyfile-only initrd through the Linux EFI initrd protocol. Your UKI's embedded initramfs must support the generated or manual keyfile option. See the LUKS root example above for the mapper-name consistency checklist.

entry {
    name      = "Arch UKI LUKS"
    icon      = \EFI\visor\icons\arch.png
    kernel    = \EFI\Linux\arch-linux.efi
    cmdline   = "rd.luks.name=12345678-1234-1234-1234-123456789abc=cryptroot root=/dev/mapper/cryptroot rw quiet"
    luks      = 1
    luks_key_path = /crypto_keyfile.bin
    luks_preset = mkinitcpio
}

Auto-detection

When boot.conf is absent or has no entry { } blocks, Visor scans the ESP:

• \EFI\Linux\*.efi → Unified Kernel Images (each becomes an entry)
• \boot\vmlinuz*, \vmlinuz* → raw kernels (fallback if no UKIs are found)
• \EFI\Microsoft\Boot\bootmgfw.efi → Windows Boot Manager

Menu controls