Garuda Toolbox

Garuda Toolbox is the graphical front end for maintenance, diagnostics and system settings on Garuda Linux. Its help menu describes it as a system maintenance and diagnostics tool that helps users maintain their system and diagnose issues. It is built with Electron and Angular. Most Garuda users reach the other tools of the Garuda apps through it. It replaces the standalone Garuda Welcome, Gamer, Boot Options, Boot Repair, Assistant and Settings Manager packages, as listed in its replaces list.

For the first steps after installing Garuda, read Post-installation tasks. This page is the reference for the app itself.

Starting it

The app has a menu entry called Garuda Toolbox. It can also be started from a terminal.

garuda-toolbox

Argument	Effect
`--setup-assistant`	Opens the Setup Assistant tab (`/setup-wizard`) on start. Used by the Setup Assistant after a successful first run.

The launcher script /usr/bin/garuda-toolbox reads extra Electron flags from ~/.config/garuda-toolbox/garuda-toolbox-flags.conf. Each line becomes one flag. Lines that start with # are ignored.

Package

Package	Notes
`garuda-toolbox`	Stable package from `pkgbuilds/garuda-toolbox`, version 6.3.0 in the PKGBUILD. Depends on `electron43`, `garuda-libs>=1.6.0`, `pacman-contrib`, `archlinux-appstream-data`, `curl` and `util-linux`.
`garuda-toolbox-git`	Git package from `pkgbuilds/garuda-toolbox-git`. It provides and conflicts with `garuda-toolbox`.

The optional dependencies are paru (pending AUR updates), meld (compare pacdiff files), pace (manage repositories), reflector-simple (mirrorlists) and btrfs-assistant (Btrfs snapshots).

The package installs these files:

/usr/bin/garuda-toolbox, the launcher script
/usr/libexec/garuda-toolbox-pty-wrapper, the wrapper for root tasks
/usr/lib/garuda-toolbox/app.asar, the application
/usr/share/polkit-1/actions/org.garudalinux.toolbox.policy, the polkit policy

Tabs

The app has 13 routes in packages/renderer/src/app/routes.ts. The menu labels come from assets/i18n/en.json.

Route	Menu label	What it shows
`/` (Garuda Toolbox)	Welcome	Start page with tiles for Maintenance, System settings, Gaming, Boot tools, Diagnostics and Network tools. It also has links to the forum, Telegram, Discord, Mastodon, Bluesky and IRC. The tile `Install Garuda Linux` and the tile `Chroot into Garuda` appear only on a live system. The tile `Setup assistant` appears only on an installed system.
`/setup-wizard`	Setup assistant	Software selection with the step `Software Selection` and the button `Apply Changes`.
`/setup-wizard-success`	none	The success page. The wizard opens it after it finishes.
`/maintenance`	Maintenance	Maintenance actions, described below.
`/packages`	Discover apps	A searchable list of applications with name, description, URL, icon and status, grouped by category.
`/system-tools`	System settings	System tools in the tabs System components, System settings, Kernels, Locales, Systemd services and Users & groups. The System components tab has the sections Audio, Bluetooth, Containers, Firewall, Miscellaneous, Network, Printing and Virtualization.
`/gaming`	Gaming	Gaming apps grouped into Game launchers, WINE, Gaming tools, Miscellaneous, Controller support, Games and Emulators.
`/diagnostics`	Diagnostics	Debug output and logs, described below.
`/settings`	App settings	Settings of the Toolbox itself, described below.
`/config-files`	Config files	Known configuration files with a description, a path, an edit action and a search field.
`/boot-repair`	Boot Repair	GRUB repair, described below.
`/boot-options`	Boot tools	GRUB and bootsplash options, described below.
`/network-assistant`	Network tools	Network status, hardware, drivers and diagnostics, described below.

Maintenance

The maintenance tab has three tabs: Common maintenance, Reset configs to default state and Garuda update rescue tools. Several of the actions wrap pacman and Btrfs tools. Labels are shown as printed.

Tab	Actions
Common maintenance	`Update system` (runs `garuda-update`), `Clean cache`, `Clear orphans`, `Remove Pacman lock`, `Refresh keyring`, `Refresh Arch mirrorlist`, `Refresh Chaotic-AUR mirrorlist`, `Merge pacdiff files`, `Edit repositories` (with Pace), `Btrfs Assistant`, `System health check` (runs `garuda-health`) and `Repair system health` (runs `garuda-health --fix`)
Reset configs to default state	`Reset configs to default state`, which lists the files it resets before it runs
Garuda update rescue tools	`Garuda update fix`, `Garuda update full fix`, `Garuda update keyring`, `Reset audio`, `Reset snapper`, `Reinstall packages`

Some actions can not be queued. The text This action can not be queued and needs to be run directly. (key maintenance.onlyDirect) describes them. The Add pending and Remove pending buttons manage the queue.

The rescue actions are explained in garuda-update fixes. The health check is explained in garuda-health.

Diagnostics

The diagnostics tab runs these commands. The system logs come from the systemd journal. Each entry shows its output in the console.

Entry	Command	Root
Common info	`garuda-inxi`	no
System services	`systemd-analyze blame --no-pager && systemd-analyze critical-chain --no-pager`	no
System logs	`journalctl -e --no-pager`	yes
Latest Pacman logs	`pkexec cat /var/log/pacman.log`, filtered to the last transaction	yes
Kernel logs	`dmesg`	yes
System health	`garuda-health`	yes
Full diagnostics	All of the above in one output	yes

Upload to PrivateBin sends the current output to PrivateBin and copies the link to the clipboard.

Boot tools and Boot Repair

The Boot tools tab (route /boot-options) edits the GRUB and Plymouth settings. The tab lists these options:

Kernel parameters and presets: Disable CPU mitigations, Always enable SysRq
Menu timeout in seconds, and Default boot entry
Save default entry, Enable flat menus and Search for other operating systems
Plymouth theme (bootsplash) and GRUB theme
Boot message detail with the levels Very Detailed (All messages), Detailed (Quiet) and Limited (Quiet + Hush)
Edit /etc/default/grub, a warning that direct edits can be overwritten by GRUB updates

The Boot Repair tab (route /boot-repair) offers Reinstall GRUB (to MBR, ESP or root), Repair GRUB configuration, Backup MBR or PBR and Restore MBR or PBR from backup.

Network tools

The network tab (route /network-assistant) has four tabs: Status, Hardware, Drivers and Diagnostics. It also has quick toggles for Wi-Fi, Bluetooth, Airplane Mode and GPS. The drivers tab can load, unload and blacklist drivers. The diagnostics tab runs Ping (with target host and timeout) and Traceroute (with max hops).

App settings

The settings tab (route /settings) has these options:

Enable dark mode and Base design theme
Configure active language and Select the log level
Auto-start application
Show links on home page and Show window buttons on the left
Custom background, Blur background and Fit background to app
Copy diagnostics to clipboard
Enable systemd services auto refresh and Show user Systemd services

The auto-start option creates the symlink ~/.config/autostart/garuda-toolbox.desktop to /usr/share/applications/garuda-toolbox.desktop (components/config/config.service.ts).

Config files, data and logs

What	Path	Source
Launcher flags	`~/.config/garuda-toolbox/garuda-toolbox-flags.conf`	`assets/garuda-toolbox.sh`
App settings and window size	Store of `electron-store` in the Electron user data folder	`packages/main/src/modules/LoggingModule.ts`, `WindowManager.ts`. The exact file name is UNCONFIRMED.
Log level	Set in App settings, stored in the same store	`packages/main/src/modules/LoggingModule.ts`
Auto-start	`~/.config/autostart/garuda-toolbox.desktop`	`components/config/config.service.ts`
Root task policy	`/usr/share/polkit-1/actions/org.garudalinux.toolbox.policy`	`assets/org.garudalinux.toolbox.policy`
Pacman log read by the diagnostics	`/var/log/pacman.log`	`components/diagnostics/diagnostics.component.ts`

The app writes its logs to the terminal with pino-pretty (packages/main/src/logging/logging.ts). The code does not write a log file. Start garuda-toolbox from a terminal to see the log output. The Git package sets the log level to VERBOSE (pkgbuilds/garuda-toolbox-git/PKGBUILD).

Root tasks use the polkit action org.garudalinux.toolbox.run. The default for it is auth_admin. Reading /etc/default/grub and /boot/grub/grub.cfg has its own actions without a password.

Known limits

Root tasks ask for an administrator password through polkit (assets/org.garudalinux.toolbox.policy).
Logs go to the terminal only. There is no log file in the code (packages/main/src/logging/logging.ts).
The start page tile Startpage sets routerLink: '/update'. The routes file has no /update route (components/home/home.component.ts, packages/renderer/src/app/routes.ts).
The Install Garuda and Chroot into Garuda tiles run only on live systems. The Setup assistant tile runs only on installed systems (components/home/home.component.ts, condition fields).
The Boot Repair tab mounts the root partition with subvol=@ (components/boot-repair/boot-repair.service.ts). A root without a Btrfs subvolume named @ will fail the chroot step.
Some maintenance actions can not be queued (maintenance.onlyDirect in assets/i18n/en.json).

Commands

garuda-toolbox
garuda-toolbox --setup-assistant
garuda-health

Garuda apps lists all Garuda apps.
Post-installation tasks covers the first steps after installing.
garuda-update is the update tool that the Update system action runs.
garuda-health is the health checker that the diagnostics tab runs.
garuda-update fixes lists the rescue actions.
Setup Assistant is the first-boot assistant that hands over to the Toolbox.
Garuda Welcome, Gamer, Boot Options, Boot Repair, Assistant and Settings Manager are the standalone predecessors of the Toolbox tabs.