Skip to content

About

Create, run and manage QEMU/KVM virtual machines from the Omarchy bar — including installing and configuring QEMU/KVM for you.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Virtual Machines — an Omarchy shell plugin

List, start, stop, and create QEMU/KVM guests from the Omarchy bar.

A bar icon shows how many machines are running. Clicking it opens a panel with every guest libvirt knows about, the actions that apply to each one, and a compact form for creating a new VM.

What it does

  • Lists every domain on the connection, with state, vCPUs, and memory.
  • Acts: start, shut down, force off, open the console in virt-viewer, and delete (with its disk images, behind a confirmation).
  • Creates: name, install ISO, memory, vCPUs, disk size, and an optional UEFI boot toggle. Pick the ISO from the folder scan, type a path, or browse for it — the browser runs inside the panel, so a half-filled form survives. The actual virt-install run happens in a floating terminal so its progress and errors stay visible.
  • Sets itself up: on a machine where QEMU/KVM is not ready, the panel says exactly what is missing and offers a one-click setup.

Requirements

Omarchy 4.0 or newer (the Quickshell-based omarchy-shell).

The plugin shells out to these; it does not bundle them:

Package Needed for
libvirt everything — virsh is how the plugin talks to the hypervisor
qemu-desktop (or qemu-full) actually running guests
virt-install creating new VMs
virt-viewer opening a guest's console
edk2-ovmf the UEFI boot option
swtpm guests that require a TPM, such as Windows 11
dnsmasq libvirt's default NAT network

You do not have to install these by hand. Omarchy's plugin installer never runs install hooks or sudo — it only clones files — so the plugin asks for what it needs the first time you open it. The panel's Set up QEMU/KVM button opens a terminal that installs the packages, enables the libvirt sockets, starts the default network, and adds you to the libvirt group. Everything privileged happens there, in front of you, with your own sudo.

The group change takes effect after you log out and back in.

If you would rather do it yourself:

sudo pacman -S --needed qemu-desktop libvirt virt-install virt-viewer edk2-ovmf swtpm dnsmasq
sudo systemctl enable --now virtqemud.socket virtnetworkd.socket \
                            virtstoraged.socket virtnodedevd.socket virtlogd.socket
sudo virsh net-autostart default && sudo virsh net-start default
sudo usermod -aG libvirt "$USER"   # then log out and back in

Installation

omarchy plugin add https://github.com/ferass04/omarchy-vm-forge --enable

Review the code before enabling it — plugins run unsandboxed inside omarchy-shell. Adding without --enable clones it disabled so you can read it first, then omarchy plugin enable io.github.ferass04.vm-forge.

To move it in the bar:

omarchy bar move io.github.ferass04.vm-forge --section right

Removal

omarchy plugin remove io.github.ferass04.vm-forge

That disables the widget and deletes ~/.config/omarchy/plugins/io.github.ferass04.vm-forge/. It does not touch your VMs, your disk images, or any package it helped install. To undo the system setup as well:

sudo systemctl disable --now virtqemud.socket virtnetworkd.socket \
                             virtstoraged.socket virtnodedevd.socket virtlogd.socket
sudo gpasswd -d "$USER" libvirt

Settings

Configurable from Setup → Plugins, or directly with omarchy bar set:

Key Default Meaning
connection Auto System uses qemu:///system, Session uses qemu:///session, Auto prefers system and falls back to session when its socket is unreachable.
refreshIntervalSec 15 How often the domain list is re-read.
isoDir ~/Downloads Scanned two levels deep for *.iso to fill the install-media picker.
defaultMemoryMb 4096 Starting value in the create form.
defaultVcpus 2 Starting value in the create form.
defaultDiskGb 40 Starting value in the create form.
omarchy bar set io.github.ferass04.vm-forge connection System

Install media and the system connection

On qemu:///system the guest is run by an unprivileged system user (libvirt-qemu on Arch), not by you. A home directory is 0700, so an ISO in ~/Downloads — this plugin's default place to look — is unreadable to that user. QEMU reports it as a bare Permission denied after allocating the disk, which is a confusing place to learn it.

The plugin checks before it gets there. It names the exact directory in the way and offers the two real fixes: grant that one user permission to pass through,

sudo setfacl -m u:libvirt-qemu:x /home/$USER    # undo: setfacl -x u:libvirt-qemu

which opens nothing to anyone else, or keep install media outside your home:

sudo mv ~/Downloads/whatever.iso /var/lib/libvirt/images/

qemu:///session runs the guest as you and is not affected.

System or session?

qemu:///system is the normal choice: guests get libvirt's default NAT network, shared storage pools, and the same view virt-manager has. It needs the libvirt sockets enabled and your user in the libvirt group.

qemu:///session needs no privileged setup at all and works immediately, but guests get user-mode (SLIRP) networking — outbound only, no inbound connections — and their disk images live under ~/.local/share/libvirt/images.

Keyboard

While the panel is open:

Key Action
n New VM
r Refresh
Esc Unwinds one layer: the confirmation, then the file browser, then the form, then the panel
Tab Move to the next bar panel

IPC

omarchy-shell io.github.ferass04.vm-forge toggle
omarchy-shell io.github.ferass04.vm-forge refresh
omarchy-shell io.github.ferass04.vm-forge list          # JSON
omarchy-shell io.github.ferass04.vm-forge create        # open the create form
omarchy-shell io.github.ferass04.vm-forge start <name>
omarchy-shell io.github.ferass04.vm-forge stop  <name>

How it is put together

File Role
Panel.qml The entry point: bar icon plus popup. Picks one of three views — setup, create, or list.
Service.qml Every libvirt call. The QML above it reads state and calls verbs; it never runs a process itself.
Model.js Pure functions — parsing, validation, virt-install argv. No I/O, so it is testable outside QML.
SetupGate.qml The "not ready yet" view and its checklist.
CreateForm.qml The quick-create form.
FileBrowser.qml In-panel install-media browser. In the panel because the panel closes on focus loss, and a terminal or portal dialog would take the half-filled form with it.
VmRow.qml One VM in the list.
bin/vm-forge-probe Reports what is and is not ready, as JSON.
bin/vm-forge-list Reports the domain list, as JSON.
bin/vm-forge-browse Lists one directory — subfolders and *.iso only — as JSON.
bin/vm-forge-setup The only place sudo appears. Run in a visible terminal, never by the shell.
bin/vm-forge-create Assembles and runs virt-install. Usable as a CLI on its own.

Nothing in the QML runs a privileged command. Guest actions are authorised by libvirt group membership; the one privileged path is the setup script, which you launch explicitly.

Development

git clone https://github.com/ferass04/omarchy-vm-forge
cd omarchy-vm-forge
./bin/dev-sync        # copy into ~/.config/omarchy/plugins/ and rescan

The shell watches ~/.config/omarchy/plugins/ and hot-reloads on write, so re-running dev-sync is the whole loop. Symlinking the checkout into place does not work — omarchy plugin validate rejects symlinks inside a plugin folder.

omarchy plugin validate .                                    # manifest
node Model.test.mjs                                          # logic
qmllint -I "$OMARCHY_PATH/shell" *.qml                       # QML

qmllint reports unqualified-access and missing-property warnings for bar.* and Style.font.*. Those are unavoidable — both are dynamically typed in the shell — and the first-party plugins produce the same ones.

License

MIT. See LICENSE.

About

Create, run and manage QEMU/KVM virtual machines from the Omarchy bar — including installing and configuring QEMU/KVM for you.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages