Documentation#

Welcome to the Vay documentation. Here you’ll find everything you need to build the ISO, install Vay, and get started with your new system.

Building the ISO#

Prerequisites#

Currently, Vay ISO images must be built manually. You’ll need a working Void Linux installation to build the ISO. Prebuilt ISO images and automated container-based builds are planned for the future.

Before you begin, make sure you have:

• A working Void Linux base system
• The required build dependencies installed
• An active internet connection
• Enough free disk space for the build and resulting ISO

Note: The Makefile does not install build dependencies. You must install the required tools yourself before building Vay.

1. Clone the repository#

git clone --depth=1 --recursive https://git.k4li.de/vay/vay-iso.git
cd vay

2. Choose your build target#

Vay currently provides three build targets:

The targets adjust the package selection for the intended platform. Laptop installations also include brightnessctl for display brightness control.

Build the ISO by running the corresponding Make target:

make amd

Replace amd with nvidia or generic as needed. Choose one target per build.

3. Find the generated ISO#

Once the build completes, the ISO will be available in the out/ directory.

The image is currently around 2 GB, although the exact size may vary between versions and build targets. The generated filename includes the Vay version, architecture, and build timestamp.

For example:

out/vay-v0.2-x86_64-202610181813.iso

4. Write the ISO to a USB drive#

First, identify your USB device:

lsblk

Then write the ISO to the correct device. Replace the example filename and /dev/sdX with your actual ISO path and USB device:

sudo dd \
  if=out/vay-v0.2-x86_64-202610181813.iso \
  of=/dev/sdX \
  bs=4M status=progress conv=fsync

Warning: Writing an ISO destroys existing data on the target device. Double-check the target before running the command. Use the whole USB device (for example, /dev/sdX), not a partition such as /dev/sdX1.

Once the command completes, safely flush pending writes before removing the USB drive.

Installation#

Installing Vay is designed to be straightforward. The live ISO automatically starts the installer after booting.

1. Boot the live ISO#

Insert your USB drive and boot your machine from it. If necessary, select the USB drive from your firmware’s boot menu.

2. Confirm the installation#

The installer starts automatically and asks you to confirm that you want to proceed.

After confirmation, an interactive menu powered by gum guides you through the configuration.

3. Configure your system#

Work through the following menu entries:

Follow the prompts in each section. Make sure your disk selection and partitioning choices are correct before starting the installation.

Warning: The disk configuration and installation process can overwrite existing data on the selected disk. Back up any important files before proceeding.

4. Install Vay#

Once your configuration is complete, select Install.

The installation typically takes around 3–5 minutes, depending on your hardware and installation conditions.

5. Reboot into Vay#

After the installer finishes, reboot your machine and boot from the installed system. You should now have a working Vay desktop ready to configure to your liking.

Getting help#

Vay is an evolving project, and some features or instructions may change between releases.

If you encounter issues while building or installing Vay, check the project repository for updates and known issues.