Overview

WolfStack lets you create and manage KVM/QEMU virtual machines directly from the web dashboard. VMs work on native WolfStack nodes (any Linux server with KVM support), libvirt/virsh nodes, Proxmox VE nodes, and XCP-ng pools via Xen Orchestra — all managed through a single interface.

XCP-ng / Xen Orchestra integration

WolfStack speaks the Xen Orchestra REST API, so XCP-ng pools become first-class citizens alongside Proxmox and native KVM:

• Unified inventory — Hosts, pools, VMs, storage repositories, networks, and snapshots all visible in the unified VM list across multiple XCP-ng pools.
• Tokenised auth — XO API tokens stored XOR-obfuscated at /etc/wolfstack/xo_pools.json; never returned to the browser.
• Type-1 awareness — Since XCP-ng is a Type-1 hypervisor (no host-level LXC), WolfStack treats VMs as the workload unit instead of trying to spawn containers on the dom0.
• Tenant federation — XCP-ng pools participate in the WolfStack federation layer for cross-cluster visibility alongside Proxmox and native nodes.
• Read-only inventory today — the current release is a unified, read-only window into your XCP-ng pools. VM lifecycle actions (start/stop/snapshot) are on the roadmap; power and provisioning stay in Xen Orchestra for now.

Connect a pool by generating an authentication token in Xen Orchestra (Settings → Users → Tokens) and registering the XO URL and token in WolfStack. WolfStack needs network access to the Xen Orchestra appliance, not directly to dom0.

Key Features

• Create VMs — Specify CPU cores, memory, disk size, and boot ISO
• ISO & IMG boot — Boot from ISO (CD-ROM) or .img files (virtual USB)
• Import disk images — Import .img, .qcow2, .vmdk, .vdi, or .vhd files as ready-to-run VMs
• VNC console — Graphical console access from the browser (works with Windows, Linux, and any OS)
• Serial terminal — One-click in-browser terminal that attaches to the guest serial console — works across native QEMU, libvirt, and Proxmox VMs
• Graceful shutdown — Separate Stop (ACPI shutdown) and Force Stop (power-yank) buttons, so a clean shutdown is the default and force is a deliberate click with a confirm dialog
• Disk management — Resize disks, add extra storage volumes, choose disk bus (virtio, IDE, SATA)
• Multi-NIC support — Add multiple network interfaces for firewalls (OPNsense, pfSense), routers, and multi-homed servers
• Physical NIC passthrough — Pass a host network adapter directly to a VM for raw L2 access (e.g. Starlink, dedicated WAN)
• WolfNet networking — Assign a WolfNet IP to make the VM reachable across your cluster
• Autostart — Configure VMs to start automatically when the host boots
• Windows support — IDE/SATA disk bus and e1000 network adapter for Windows compatibility, VirtIO drivers ISO support
• Libvirt integration — On systems with libvirtd, WolfStack auto-discovers and manages existing VMs via virsh — no reinstallation needed
• Proxmox integration — On Proxmox nodes, VMs are created and managed via the PVE API with full feature parity

Creating a VM

Navigate to a node in the sidebar, then click VMs. Click Create VM and fill in:

Serial Terminal

Click the 💻 Terminal button next to any running VM to open an in-browser serial console. The same button works across all three VM backends — WolfStack picks the right connection path:

• Native QEMU — socat attaches to the per-VM Unix socket at /var/lib/wolfstack/vms/<name>.serial.sock (wired up for you at VM start time).
• libvirt — virsh console <name> --force. The --force disconnects any stale console holder so your web session doesn't get stuck behind a previous attach.
• Proxmox — resolves the VM name to its VMID and runs qm terminal <vmid>. WolfStack-created PVE VMs get serial0: socket automatically; VMs imported from the Proxmox web UI may not — WolfStack pre-flights the check and pops a one-click Add serial console prompt if it's missing.

Guest-side requirements

The host side is automatic, but the guest OS still needs to log to the serial port the same way it would for a physical serial console. If the terminal opens but stays blank, the guest needs:

• console=ttyS0 (or console=ttyS0,115200) on the kernel command line
• A getty running on ttyS0 (or the equivalent — systemctl enable serial-getty@ttyS0 on systemd distros)

Once enabled these stick — the terminal will land on a login prompt every time you open it. WolfStack prints a short reminder at the top of the terminal each time so you can spot the setup issue quickly.

Stop vs Force Stop

Running VMs have two stop buttons with distinct meanings:

Internal paths that need a guaranteed immediate stop — VM delete and cross-node migration export — still force-stop. Those semantics haven't changed.

Cluster-Native VMs

VMs carry a host_id tag in their config identifying the node that owns them. The tag is stamped on create, rewritten on migration, and used by the cluster view to render VMs as first-class members under the right host — no manual Scan needed. Combined with a WolfNet IP, a VM becomes a cluster citizen that can be reached from any other node by IP, regardless of which host it's actually running on.

Attaching an ISO

ISOs provide the installation media for your VM — like inserting a CD. The ISO is attached as a virtual CD-ROM drive and the VM boots from it.

Native WolfStack Nodes

Upload or download the ISO to any path on the server, then enter the full path:

# Download an ISO
sudo mkdir -p /opt/isos
sudo wget -O /opt/isos/ubuntu-24.04.iso https://releases.ubuntu.com/24.04/ubuntu-24.04-live-server-amd64.iso

# Then enter in WolfStack:
/opt/isos/ubuntu-24.04.iso

Proxmox Nodes

On Proxmox, ISOs must be uploaded to a storage first (via the Proxmox web UI or CLI), then referenced using the Proxmox storage format:

local:iso/ubuntu-24.04-live-server-amd64.iso

You can also upload ISOs via the Proxmox web UI at Datacenter → Storage → ISO Images → Upload.

Detaching an ISO

After installing the OS, remove the ISO so the VM boots from disk:

1. Stop the VM
2. Go to VM Settings
3. Clear the ISO path field
4. Start the VM — it will now boot from the disk

Booting from .img Files

Some operating systems distribute disk images as .img files instead of ISOs (e.g. Raspberry Pi OS, Alpine cloud images, OpenWrt). WolfStack attaches these as a virtual USB drive so the VM can boot and install from them, just like plugging in a USB stick.

Use the Boot Media field and enter the path to the .img file:

/opt/isos/alpine-virt-3.20.0-x86_64.img

WolfStack auto-detects the file type: .iso files are attached as CD-ROM, .img and .raw files are attached as USB.

Importing Disk Images

If you have a pre-built disk image (a cloud image, an exported VM, or a downloaded appliance), you can import it directly as the OS disk instead of installing from scratch. WolfStack converts it to qcow2 format automatically.

Supported Formats

How to Import

1. Download or copy the disk image to the server
2. Create a new VM and enter the path in the Import Image field
3. Set the disk size to at least the size of the image (it will be expanded if larger)
4. Leave the Boot Media field empty — the imported image is already a bootable disk

# Example: download an Ubuntu cloud image
sudo mkdir -p /opt/images
sudo wget -O /opt/images/ubuntu-24.04-cloud.img https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img

# Then enter in WolfStack Import Image field:
/opt/images/ubuntu-24.04-cloud.img

Console Access

VMs provide a VNC graphical console — unlike containers which use a text terminal. This works with any operating system including Windows.

• Click the Console button on any running VM to open the VNC viewer in a new window
• The viewer supports keyboard, mouse, and clipboard
• Ctrl+Alt+Del button available in the toolbar for Windows login screens
• Fullscreen mode available

Works from any node in the cluster — open the console from the cluster dashboard and WolfStack securely bridges the session to whichever node runs the VM. You don't have to log into the VM's own node.

External VNC clients New in v24.35

Prefer TigerVNC, RealVNC or Remmina? Tick External VNC in the VM's settings: WolfStack puts the VM's VNC on the network with a generated password (shown in the VM editor — never stored in plain text) and opens the firewall port for as long as the VM runs. Off by default; the in-browser console keeps working either way.

Windows VMs

Creating a Windows VM requires specific settings for compatibility:

After installing Windows with IDE/e1000, you can optionally install VirtIO drivers inside Windows and switch to virtio for better performance.

VM Settings

To modify a VM, stop it first, then open VM Settings:

• CPU & Memory — Change core count and RAM allocation
• Disk Resize — Increase the OS disk size (cannot shrink)
• Extra Disks — Add additional storage volumes
• Network Adapter — Change the primary NIC model (virtio, e1000, rtl8139)
• WolfNet IP — Assign a WolfNet IP for cross-node access
• Additional NICs — Add, remove, or modify extra network interfaces
• ISO — Attach or detach installation media
• BIOS Type — Switch between SeaBIOS (legacy) and OVMF (UEFI)
• Boot Order — Choose what the VM boots from and in what sequence (disk, CD/ISO, network, USB) — new in v24.35
• USB Boot — Boot the VM from a passed-through USB stick, e.g. for installers and recovery media — new in v24.35
• Autostart — Toggle automatic start on host boot

VM Lifecycle

Storage

VM disk images are stored as qcow2 files on native WolfStack nodes:

• Default location: /var/lib/wolfstack/vms/
• Each VM has a config JSON and one or more disk images
• Extra disks can be added for additional storage

On Proxmox, storage is managed by PVE and can use local-lvm, ZFS, Ceph, NFS, or any configured Proxmox storage backend.

Networking

Every VM has a primary NIC (net0) configured during creation. You can also add extra NICs for multi-homed configurations.

• User-mode networking — Default. The VM gets NAT access to the host network via QEMU’s built-in DHCP. No bridge needed.
• WolfNet IP — Assign an IP in VM Settings to create a TAP interface on WolfNet, making the VM reachable across your cluster mesh.
• Bridge mode — Attach a NIC to a host bridge (e.g. br0, vmbr1) for direct L2 network access. The VM gets its own IP on the physical network.
• Proxmox — On PVE nodes, networking is managed via Proxmox bridges (vmbr0, vmbr1, etc.).
• vSwitch VLAN — Put a NIC on a provider vSwitch (Hetzner vSwitch, OVH vRack, generic 802.1Q): pick the uplink NIC and VLAN ID and WolfStack auto-creates the tagged sub-interface and bridge. Because a VM’s address lives inside the guest, it is staged via cloud-init — ipconfigN on Proxmox VMs, a NoCloud seed ISO for libvirt — and applied on the VM’s next boot. See Networking.

Multiple Network Interfaces (Multi-NIC)

VMs can have multiple network interfaces — essential for firewalls like OPNsense and pfSense which need separate WAN and LAN interfaces, or for routers, load balancers, and multi-homed servers.

How It Works

The primary NIC (net0) is configured in the main Network section. Additional NICs (net1, net2, ...) are added in the Additional Network Interfaces section on the Network & Boot tab.

Each extra NIC has the following settings:

Adding Extra NICs

1. Open Create VM or VM Settings (VM must be stopped)
2. Go to the Network & Boot tab
3. Click + Add NIC in the Additional Network Interfaces section
4. Choose the NIC model, enter a bridge name (or leave blank), and optionally set a MAC
5. Repeat for each additional NIC needed
6. Click Create or Save

Physical NIC Passthrough

Physical NIC passthrough lets you give a VM direct access to a host network adapter without manually configuring bridges. This is ideal for:

• Starlink or dedicated WAN — Pass the Starlink adapter to OPNsense so it can run DHCP and manage the connection
• Multi-homed servers — Attach VMs directly to specific physical networks
• Firewall WAN/LAN separation — Give each firewall interface its own physical NIC

When you select Physical NIC mode, WolfStack:

1. Shows a dropdown of available physical interfaces on the host (with driver and link speed)
2. Auto-creates a dedicated bridge for the selected interface (vmbr{N} on Proxmox, br-pt-{name} on native)
3. Flushes any host IP from the interface (the VM takes over)
4. Attaches the VM’s NIC to the bridge

If the host later reboots, Proxmox bridges are persisted via pvesh. On native nodes, the bridge is recreated automatically when the VM starts.

Example: OPNsense Firewall with Starlink

OPNsense requires at least two NICs — one for WAN (internet) and one for LAN (internal network). Here’s how to set it up with a Starlink adapter:

1. Create a VM with 2 CPU cores, 2048 MB RAM, 20 GB disk
2. Attach the OPNsense ISO as boot media
3. Add NIC (WAN) — Set mode to Physical NIC, select your Starlink adapter from the dropdown
4. Add NIC (LAN) — Set mode to Physical NIC, select your LAN adapter
5. Start the VM and install OPNsense
6. OPNsense will detect both interfaces — assign WAN to the Starlink NIC and LAN to the other
7. OPNsense gets a DHCP address from Starlink and serves your LAN

How Bridged NICs Work Internally

For each extra NIC with a bridge specified (or Physical NIC passthrough), WolfStack:

1. Creates a TAP interface (e.g. tap-myvm-1) on the host
2. Attaches the TAP to the bridge (ip link set tap-myvm-1 master br1)
3. Passes the TAP to QEMU as -netdev tap,id=net1,ifname=tap-myvm-1
4. On VM stop, the TAP is cleaned up automatically

If no bridge is specified, the NIC uses QEMU user-mode networking (NAT through the host, no bridge needed).

USB/PCI Device Passthrough

WolfStack supports passing USB devices, GPUs, NVMe drives, network cards, and any other PCI device directly to a VM. The VM gets exclusive, near-native access to the hardware — essential for GPU compute, NVMe storage, and dedicated network interfaces.

Supported Devices

• GPUs — NVIDIA, AMD, and Intel GPUs for gaming, AI/ML inference, or transcoding (e.g. Plex hardware transcoding)
• NVMe drives — Pass an entire NVMe SSD to a VM for native storage performance
• USB devices — USB drives, dongles, hardware security keys, serial adapters, Zigbee/Z-Wave sticks
• Network cards — Dedicated NICs for firewall VMs, storage appliances, or network testing
• Any PCI device — Coral TPU, capture cards, HBAs, RAID controllers, and more

IOMMU Group Detection

WolfStack automatically scans your system’s IOMMU groups and shows which devices can be passed through safely. Each PCI device belongs to an IOMMU group — all devices in the same group must be passed through together. WolfStack:

• Detects whether IOMMU is enabled (intel_iommu=on or amd_iommu=on)
• Lists all IOMMU groups with their member devices
• Warns if a group contains devices that cannot be safely detached (e.g. the host’s boot disk controller)
• Shows the current driver binding for each device (e.g. nvidia, nvme, vfio-pci)

Three-Backend Support

Device passthrough works on all three VM backends:

Conflict Detection

Before passing a device through, WolfStack checks for conflicts:

• Driver conflicts — Warns if a device is currently in use by a host driver (e.g. the NVIDIA driver has the GPU)
• IOMMU group sharing — Warns if other devices in the same group would be affected
• Already attached — Prevents passing the same device to multiple VMs
• Boot-critical devices — Refuses to detach the host’s primary disk controller or console GPU

How to Pass Through a Device

1. Ensure IOMMU is enabled in your BIOS/UEFI and kernel parameters (intel_iommu=on or amd_iommu=on)
2. Open Create VM or VM Settings (VM must be stopped)
3. Go to the Hardware tab
4. Click + Add PCI Device or + Add USB Device
5. Select the device from the dropdown — WolfStack shows the device name, IOMMU group, and current driver
6. Click Create or Save

WolfStack handles driver unbinding and VFIO binding automatically. On VM stop, devices are released back to the host.

Automatic Cleanup on VM Delete New

When a VM with passed-through devices is deleted, WolfStack now releases every assigned device back to the host kernel automatically — no leftover VFIO bindings, no orphaned NICs the host can’t see.

• Device rebind — PCI devices are unbound from vfio-pci and rebound to their original host driver (nvidia, iwlwifi, e1000e, etc).
• Netplan drop-in restore — for passed-through NICs, the original netplan drop-in is rewritten so the interface comes back up with its prior IP/DHCP config on the next netplan apply.
• Works on both paths — identical behaviour on libvirt-managed and Proxmox-managed VMs. Delete a VM the same way regardless of hypervisor backend.

Libvirt Integration

On systems with libvirtd running, WolfStack automatically detects and manages all libvirt VMs — no adoption or import step needed. VMs appear in the dashboard just like they do on Proxmox.

How It Works

WolfStack checks for a running libvirt daemon on startup (via virsh uri). If detected, all VM operations are delegated to virsh:

Migrating from Libvirt to WolfStack

If you have existing VMs managed by libvirtd, there’s nothing to migrate. Install WolfStack and your VMs appear automatically in the dashboard. WolfStack manages them through virsh without modifying your libvirt configuration.

Detection Priority

WolfStack auto-detects the virtualisation platform in this order:

1. Proxmox VE — If pct (Proxmox Container Toolkit) is installed, WolfStack uses the Proxmox API
2. Libvirt — If virsh uri succeeds (libvirtd is running), WolfStack uses virsh commands
3. Native QEMU — Otherwise, WolfStack manages QEMU directly (no hypervisor layer)

Requirements

• KVM support — The host CPU must support hardware virtualisation (Intel VT-x or AMD-V). Check with: grep -c vmx /proc/cpuinfo
• QEMU — Installed automatically by WolfStack when creating your first VM
• Libvirt (optional) — If libvirtd is running, WolfStack manages VMs through virsh. Install with: apt install libvirt-daemon-system virt-install
• Proxmox VE (optional) — On Proxmox nodes, VMs are managed via the PVE API (no additional setup needed)