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.
- 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-installrun 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.
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 inomarchy plugin add https://github.com/ferass04/omarchy-vm-forge --enableReview 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 rightomarchy plugin remove io.github.ferass04.vm-forgeThat 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" libvirtConfigurable 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 SystemOn 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-qemuwhich 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.
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.
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 |
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>| 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.
git clone https://github.com/ferass04/omarchy-vm-forge
cd omarchy-vm-forge
./bin/dev-sync # copy into ~/.config/omarchy/plugins/ and rescanThe 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 # QMLqmllint 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.
MIT. See LICENSE.