vmTUI

A terminal UI for managing local QEMU virtual machines. Create, launch, stop, edit, and delete VMs with an interactive keyboard-driven interface.

Shown below is the built-in ISO catalog screen with distro variants and cached image detection.

Features

• Interactive TUI built with Bubble Tea
• Manage QEMU virtual machines with keyboard shortcuts
• Download OS installer ISOs from a built-in catalog
• Boot installer ISOs directly into VMs
• View VM logs and manage disk assets
• Customizable color themes via tui/colors.json

Requirements

Without Nix

The following must be installed on your system:

• Go (1.24+) — to build and run the application
• QEMU (qemu-system-x86_64) — to run virtual machines
• aria2 — to download ISO images from the catalog

On Debian/Ubuntu:

sudo apt install golang-go qemu-system-x86 aria2

On Arch Linux:

sudo pacman -S go qemu-full aria2

On Fedora:

sudo dnf install golang qemu-system-x86 aria2

With Nix

• Nix with flakes enabled

Installation

Using Nix (recommended)

Run directly from the flake:

nix run github:yoptabyte/vmTUI

Or clone and run:

git clone https://github.com/yoptabyte/vmTUI.git
cd vmTUI
nix run .

Add to your Nix profile:

nix profile install github:yoptabyte/vmTUI

Then run vmtui from anywhere:

vmtui

Enter the development shell:

nix develop
go run .

Without Nix

Clone the repository and run with Go:

git clone https://github.com/yoptabyte/vmTUI.git
cd vmTUI
go run .

Or build a standalone binary:

go build -o vmtui .
./vmtui

Usage

Once the TUI is running, use these keyboard shortcuts:

Key	Action
↑↓/jk	Navigate VM list
enter	Launch selected VM
s	Stop running VM
i	Boot installer ISO
d	Download ISO catalog
a	Manage assets
n	Create new VM
e	Edit selected VM
l	View VM log
x	Delete selected VM
q	Quit

Configuration

Colors

Edit tui/colors.json to customize the color theme. The file uses a simple JSON format:

{
  "bg":         "#11111B",
  "panel":      "#1E1E2E",
  "border":     "#313244",
  "accent":     "#CBA6F7",
  "text":       "#CDD6F4",
  "subtext":    "#A6ADC8",
  "muted":      "#7F849C",
  "success":    "#A6E3A1",
  "danger":     "#F38BA8",
  "warning":    "#F9E2AF"
}

After changing colors, rebuild the application.

License

MIT — see LICENSE for details.