Garuda Setup Assistant

The Garuda Setup Assistant is a small Qt window that runs once after the first boot of an installed system. It applies the initial system update, offers the proprietary NVIDIA drivers when they are available, and then hands over to the Garuda Toolbox. Its package description says it is a setup utility for Garuda Linux that helps set up and install applications.

The name is also used by the Toolbox tab Setup assistant (route /setup-wizard). That tab installs software from a selection list. It is a different program. See Garuda Toolbox.

For the software selection and other first steps, read Post-installation tasks.

Starting it

The app starts in three ways.

On the first boot, the autostart entry setup-assistant AUTOSTART runs it. The entry comes from /etc/skel/.config/autostart/setup-assistant.desktop.
The menu entry Setup Assistant starts it without the AUTOSTART argument. The entry is /usr/share/applications/setup-assistant.desktop.
A terminal starts it with setup-assistant.

setup-assistant

With the argument AUTOSTART, the program exits without a window when the start is not a first boot, or when it runs in the live system (/run/miso exists). In that case it hands over to the Toolbox right away.

Package

Package	Notes
`garuda-setup-assistant`	From `pkgbuilds/garuda-setup-assistant`, version 5.1.0 in the PKGBUILD. Depends on `yad`, `wget`, `garuda-libs` and `qt6-base`. Optional dependency: `pamac`.

The CMake project builds the binary setup-assistant into /usr/bin. The translations are compiled into the binary from the i18n folder, one file for each language.

Steps

The window moves through these states. Each state is one page of the window.

State	What the window shows	What runs
Welcome	`Welcome to Garuda Linux!` and the buttons Ok and Cancel	Nothing. Cancel moves to the quit page.
Internet	`Waiting for an internet connection...`	A HEAD request to `https://garudalinux.org`, repeated until it succeeds.
Update	`Waiting for update to finish...`	`garuda-update remote setup` in a terminal, started by `/usr/lib/garuda/launch-terminal`.
Update failed	`Update failed!` and `System update failed. Try again?` with the buttons Yes and No	Yes starts the Internet state again.
NVIDIA check	`Checking for NVIDIA drivers...`	`garuda-hardware-tool --nonfree --check`, only if the tool is installed.
NVIDIA	`NVIDIA drivers` and the question whether to install the nonfree drivers, with the buttons Yes and No	Yes starts the NVIDIA apply state. No goes to the Success state.
NVIDIA apply	`Installing NVIDIA drivers...`	`sudo garuda-hardware-tool --nonfree` in a terminal.
Quit	`Before you go` with the buttons Ok and Reset	Ok closes the app. Reset returns to the Welcome state.
Success	Closes the window	Starts `garuda-toolbox --setup-assistant` and replaces the autostart entry (see below).

The NVIDIA step only appears when /usr/bin/garuda-hardware-tool exists and its --check output contains nvidia.

Handover to the Toolbox

After the Success state, the program does three things.

It removes ~/.config/autostart/setup-assistant.desktop.
It creates the symlink ~/.config/autostart/garuda-toolbox.desktop to /usr/share/applications/garuda-toolbox.desktop.
It starts garuda-toolbox --setup-assistant detached.

The handover is skipped when the environment variable VERSION is set to 4 or lower. In that case the autostart entry stays unchanged.

Config files and state

What	Path	Notes
Autostart entry	`~/.config/autostart/setup-assistant.desktop`	Copied from `/etc/skel` for new users. Removed after the handover.
First boot flag	`QSettings` key `firstBoot`	Set to false on the first start. The file path is UNCONFIRMED. Qt usually stores it under `~/.config/garuda/`.
Toolbox autostart	`~/.config/autostart/garuda-toolbox.desktop`	Created by the handover.

The first-boot check runs last reboot -n 2 --time-format notime and treats the start as a first boot when the output has exactly one line (qt/main.cpp).

The program writes its messages with qInfo and qDebug. The code does not write a log file.

Environment variables

Variable	Effect
`SETUP_ASSISTANT_SELFUPDATE`	Skips the update step and goes to the success state (`qt/setupassistant.cpp`).
`VERSION`	When 4 or lower, the handover to the Toolbox is skipped (`qt/main.cpp`).

Known limits

The Internet state repeats the request until it succeeds. The window has no cancel button in this state (qt/setupassistant.cpp, doInternetUpRequest).
The close button of the window is removed (qt/setupassistant.cpp, constructor). The Quit state is the only exit.
The update step runs garuda-update remote setup. If it fails, the program asks again. The text says that finishing this update is recommended to apply release-specific fixes.
The package depends on yad and wget. The source code does not call either tool (qt/, CMakeLists.txt). Whether the packages are needed at all is UNCONFIRMED.

Commands

setup-assistant
garuda-hardware-tool --nonfree --check
sudo garuda-hardware-tool --nonfree

Garuda apps lists all Garuda apps.
Garuda Toolbox is the app that the Setup Assistant hands over to.
Post-installation tasks covers the first steps after installing.
garuda-update is the update tool that the update step runs.