// 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.

File syntax

• One key = value per line. Whitespace around = is ignored.
• # starts a comment. Inside a value it only counts when preceded by whitespace, so title_color=#7AA2F7 is a color, not a comment. Quote a value to keep a # that follows a space.
• Quote values containing spaces: cmdline = "root=... rw quiet". The surrounding quotes are stripped.
• Entry blocks are entry { ... }. Blank lines and comments inside a braced block are fine; the block ends at its }. If you omit the braces, the first blank line ends the block — so brace your entries.
• Repeating a key keeps the last value. Unknown keys are ignored, and an invalid value is logged and the previous setting kept.
• UTF-8 and UTF-16 (with or without BOM) are both accepted.

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

Every key on this page is also described in machine-readable form in docs/boot.conf.schema.json (JSON Schema draft 2020-12, installed to /usr/share/visor/boot.conf.schema.json) — types, defaults, permitted values, aliases and grouping, generated from the parser. Use it to validate a config in an editor or a script.

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

Global keys sit at the top of the file, outside any entry { } block. They are grouped below by what they affect; the file itself accepts them in any order.

Boot behaviour

What gets booted, and whether the menu is shown at all.

Boot self-heal

Every startup, Visor looks after its own NVRAM entry and fallback binary, so OS updates (Windows in particular) can't silently walk off with the boot entry. Nothing is written when there is nothing to fix, and removable media are never touched.

Since 1.5.6, corrupted Boot#### Visor entries are detected and handled separately: a malformed (non-4-digit) Visor entry is left in place but flagged, visor status reports present (corrupted — run visor update --boot-entry to fix), and visor update --boot-entry recreates a fresh valid entry.

Entry discovery

Where Visor looks for bootable things, and which extra entries it synthesises. Auto-detection only runs when boot.conf lists no entries of its own.

Menu appearance and input

The menu's overall shape. Finer styling lives in the sections below — Colors, Icons, Logo, Underline, Blur, Animation.

Diagnostics

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

Every key in this table (and every other color key on this page) accepts the same four forms: #RRGGBB for an explicit color, an accent role name such as tertiary to follow the wallpaper palette, 1/on for that element's default accent role, or 0/off to keep the plain color. A key you leave out keeps the element's own default. Tip: title_color=#7AA2F7 is a color; title_color = #7AA2F7 with a space before # would be parsed as title_color plus a comment — write title_color=#7AA2F7 or quote the value.

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.

Picking a role per element

The keys above are on/off switches for whole groups. Any individual color key can instead name the role it should take, so one element can break away from the group:

accent           = 1            # derive the palette
underline_color  = tertiary     # ...but the underline follows tertiary
title_color      = #FFFFFF      # ...and the title stays plain white

Valid role names: primary, on_primary, primary_container, on_primary_container, secondary, tertiary, tertiary_container, surface, surface_container, on_surface, on_surface_variant, outline, clock. Hyphens work in place of underscores.

Precedence, most specific first: the element's own key (underline_color) beats its group key (accent_underline), which beats the global accent, which beats the element's built-in default. An explicit #RRGGBB always wins over the derived palette — setting a color is how you opt one element out. A role name needs a palette, so it falls back to the element's normal color when the wallpaper yields none.

Clock

A live clock rendered in the boot menu, outside the selection highlight so it ticks without forcing a full redraw. Shown only when enabled; position, format and decoration are configurable. The time is read from the firmware RTC.

Tip — the clock is the cheapest live element: it repaints only its own band. The header, entries and power actions stay cached. Combine clock_blur=1 with a detailed wallpaper for a subtle glass clock, or leave it off for a minimal look.

Screensaver

Idle dim and blank stages while the graphical menu is up. Visor tracks keys, pointer moves and clicks; after a period without activity the UI elements fade out leaving only the background (plus the clock, if enabled and kept). After a longer idle time the panel blanks to black and stops rendering until the next input.

Idle tracking is suspended while the boot countdown is running, while the text editor is open (e), or while the file browser is open — those are active use even without new keystrokes. Waking from dim cross-fades back; waking from blank fades the menu up from black and restarts the countdown so a stray key never instantly boots. Animated backgrounds keep playing while dimmed but are fully idle while blanked. The cursor's backing store is dropped across the transition so no ghost remains.

Sound

Visor can play a short .wav at startup while the menu is initialising, using its built-in Intel HD Audio driver — no external driver and no dependence on the OS ever having configured audio. The sound is upsampled to 48 kHz and played once, in parallel with the menu fade-in, so sound and picture arrive together. Sounds longer than 4 s are truncated at 4 s.

Audio needs a functional Intel HD Audio (HDA) controller and codec — see Features → Sound for how the driver picks an output (headphones take priority over built-in speakers when a jack is present).

Measured boot & Boot Loader Interface

TPM2 measured boot and systemd Boot Loader Interface interop. Both are on by default when the platform supports them; set either to 0 to disable entirely.

For an OS agent the one-shot variables are the one-boot mechanism: write LoaderEntryOneShot with an entry id and Visor boots it immediately this once, then deletes the variable; ditto for LoaderConfigTimeoutOneShot and the countdown. LoaderDevicePartUUID and LoaderEntries let the OS discover where Visor lives and what it can boot without parsing the ESP.

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. Each record targets an entry with entry = <exact menu name> (preferred) or os = <text> as a fuzzy fallback. 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 {
    entry   = Arch Linux         # target entry — exact menu name (preferred)\n    os      = Arch Linux         # fuzzy name-substring fallback
    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 (scope controlled by the scan global key above):

• \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