vmcontrol

Cross-platform QEMU/KVM virtual machine management system written in Rust. Provides a web-based control panel and REST API for full VM lifecycle management -- from creating disks and booting VMs to live migration, backups, and VNC console access.

git clone https://github.com/toey/vmcontrol.git
cd vmcontrol

# Install (pick your OS)
# macOS:    sudo bash mac/install.sh
# Linux:    sudo bash linux/install.sh
# Windows:  run windows\install.bat as Administrator

# Open Web UI
open http://localhost:8080

VNC uses QEMU's built-in WebSocket support. No external websockify or Python required. swtpm is needed for TPM 2.0 emulation (required by Windows 11).

sudo bash mac/install.sh

Installs as a launchd daemon.

sudo launchctl stop com.vmcontrol.vm_ctl
sudo launchctl start com.vmcontrol.vm_ctl

# Reload service
sudo launchctl unload /Library/LaunchDaemons/com.vmcontrol.vm_ctl.plist
sudo launchctl load /Library/LaunchDaemons/com.vmcontrol.vm_ctl.plist

sudo bash linux/install.sh

Installs as a systemd service.

sudo systemctl status vmcontrol
sudo systemctl start vmcontrol
sudo systemctl stop vmcontrol
sudo systemctl restart vmcontrol
sudo journalctl -u vmcontrol -f

Firewall:

sudo ufw allow 8080/tcp                                          # UFW
sudo firewall-cmd --add-port=8080/tcp --permanent && sudo firewall-cmd --reload  # firewalld

Run as Administrator

cd windows
.\install.bat

Installs as a Windows Service (NSSM) or Scheduled Task.

nssm status vmcontrol
nssm stop vmcontrol
nssm start vmcontrol
nssm restart vmcontrol

ARM64 note: Install the QEMU ARM64 build from qemu.weilnetz.de/aarch64. The installer detects this automatically.

# config.yaml
qemu_path: /usr/bin/qemu-system-x86_64
qemu_img_path: /usr/bin/qemu-img
qemu_aarch64_path: /usr/bin/qemu-system-aarch64
edk2_aarch64_bios: /usr/share/qemu/edk2-aarch64-code.fd
ctl_bin_path: /opt/ctl/bin
pctl_path: /tmp/vmcontrol
disk_path: /tmp/vmcontrol/disks
iso_path: /tmp/vmcontrol/iso
live_path: /tmp/vmcontrol/backups
gzip_path: /usr/bin/gzip
db_path: /tmp/vmcontrol/vmcontrol.db
mds_config_path: /tmp/vmcontrol/mds.json
domain: localhost
qemu_accel: hvf:tcg           # macOS: hvf:tcg, Linux: kvm:tcg
qemu_machine: pc
ovs_vsctl_path: /usr/bin/ovs-vsctl
bridge_sudo: true              # Use sudo for bridge mode
bridge_sudo_path: /usr/bin/sudo
internal_mcast_port: 11111     # VM-to-VM multicast port

The installer generates this file automatically. Edit to customize.

The installer also downloads virtio-win-0.1.285.iso to the ISO directory automatically (needed for Windows guest VMs).

Ensure qemu-system-aarch64 and EDK2 UEFI firmware (edk2-aarch64-code.fd) are installed. Select aarch64 architecture when creating a VM. Uses QEMU virt machine type with virtio-gpu-pci display.

Secure Boot (ARM64): Windows ARM64 VMs automatically use AAVMF Secure Boot firmware (AAVMF_CODE.secboot.fd + AAVMF_VARS.ms.fd) with Microsoft keys pre-enrolled. Install the firmware files to the path configured in edk2_aarch64_secure_code / edk2_aarch64_secure_vars. Linux ARM64 VMs use the standard edk2-aarch64-code.fd.

# Enable by setting environment variable
export VMCONTROL_API_KEY="your-secret-key"

# All /api/* endpoints require the header
curl -H "X-API-Key: your-secret-key" http://localhost:8080/api/vm/list

If VMCONTROL_API_KEY is not set, all requests are allowed without authentication. Static files and EC2 metadata endpoints always bypass auth.

Base URL: http://localhost:8080

Supported upload formats: qcow2, vmdk, vdi, vhdx, raw, img

Auto-assigns VNC ports from range 12001-13000.

VMs can query metadata at http://169.254.169.254 (or the host gateway):

/2009-04-04/user-data
/2009-04-04/meta-data/instance-id
/2009-04-04/meta-data/hostname
/2009-04-04/meta-data/local-ipv4
/2009-04-04/meta-data/public-keys/0/openssh-key
/2009-04-04/meta-data/network/interfaces/macs/{mac}/local-ipv4s

Each VM network adapter supports one of three modes:

NAT is the default mode. VMs can reach the internet but the host cannot initiate connections to VMs. Use port forwarding to expose VM services:

# Forward host:2222 -> guest:22 (SSH)
curl -X POST http://localhost:8080/api/vm/{smac}/portforward \
  -H "Content-Type: application/json" \
  -d '{"protocol":"tcp","host_port":"2222","guest_port":"22"}'

VMs on NAT mode get auto-assigned internal IPs from 192.168.100.0/24 for direct VM-to-VM communication via QEMU socket multicast. The Internal Net tab shows the IP pool and assignments.

Switches create Layer 2 segments for VM-to-VM traffic. Implementation varies by platform:

VMs on the same switch can be isolated with VLANs (0-4094):

• VLAN 0 = untagged (talks to all VMs on the switch)
• VLAN 1-4094 = tagged (only talks to same VLAN)

Bridge mode gives VMs an IP address on the host's physical network. The host can directly ping/SSH into VMs.

Bridge mode requires sudo by default. Configure bridge_sudo: false in config.yaml to disable.

The VNC console includes a Send Files button for transferring files into running VMs. Two methods are available:

Works on all VMs without any guest software. Files are packaged into an ISO image and auto-mounted on an available CD drive (cd0-cd3).

1. Click "Send Files" in the VNC toolbar
2. Drag & drop files (or click to browse)
3. Select "CD Drive (ISO)" method
4. Click Send -- ISO is created and mounted automatically
5. Access files from the CD drive inside the VM

Writes files directly to the VM filesystem via QEMU Guest Agent. Requires qemu-guest-agent installed in the guest:

• Linux VMs: Auto-installed via cloud-init. Or manually: apt install qemu-guest-agent
• Windows VMs (x86_64): Install from the auto-mounted virtio-win ISO (D: drive): run virtio-win-guest-tools.exe or guest-agent\qemu-ga-x86_64.msi
• Windows VMs (ARM64): Guest agent is not included in virtio-win ISO for ARM64. Use the ISO method instead

All VMs are provisioned with virtio-serial devices for guest agent communication. The VNC modal auto-detects agent availability and shows the appropriate method.

Windows VMs get automatic enhancements:

• TPM 2.0: swtpm emulator provides TPM device (required for Windows 11)
• virtio-win ISO: Auto-mounted on cd3 for driver and guest agent installation
• UEFI NVRAM preservation: Windows Boot Manager entries are preserved when cloning templates. Per-VM {smac}_efivars.fd files store UEFI boot configuration
• VNC toolbar buttons: Shift+F10 (CMD during install), Alt+Shift (switch language), Win11 Bypass (registry bypass for TPM/SecureBoot/NRO checks), Ctrl+V Paste
• Secure Boot (ARM64): AAVMF firmware with Microsoft keys pre-enrolled

The Create VM form includes templates with recommended defaults:

Custom templates can be created, updated, and deleted via the OS Templates API or the Web UI.

Each template can be mapped to a base disk image (persisted in DB). When you select a template:

1. The mapped base image is found
2. A clone is created automatically with name {vm-name}-disk0
3. The cloned disk is set as Disk 0 -- ready to boot

This means each VM gets its own independent disk copy from the base image.

Disk I/O can be throttled per disk with 6 presets:

Each VM can be configured with cloud-init metadata:

• Hostname -- auto-generated or custom
• SSH Public Key -- select from saved keys or paste manually
• Root Password -- default: changeme
• Custom Userdata -- additional cloud-init YAML
• Internal IP -- auto-assigned from pool for VM-to-VM networking
• Auto-install packages -- qemu-guest-agent is installed automatically on Linux VMs
• Timezone -- e.g. Asia/Bangkok
• Locale -- e.g. en_US.UTF-8
• DNS Nameservers -- comma-separated (e.g. 8.8.8.8, 1.1.1.1)
• NTP Servers -- comma-separated
• Swap Size -- auto-create swap file (MB)
• Phone Home URL -- cloud-init completion callback
• Power State -- action after cloud-init completes (poweroff/reboot/none)
• Disable Root SSH -- toggle
• Growpart -- auto-expand root partition
• Extra Packages -- comma-separated additional packages
• Extra Runcmd -- additional shell commands (one per line)
• Write Files -- JSON array of files to write

The metadata service is EC2-compatible. VMs query it for their configuration during boot via cloud-init's NoCloud datasource.

SSH public keys can be saved with names in the database. When configuring a VM's cloud-init, select a saved key from the dropdown instead of copy-pasting.

Export stopped VM disks with optional format conversion:

# Original qcow2 (fastest, no conversion)
curl -O http://localhost:8080/api/disk/export/mydisk

# Convert to other formats
curl -O "http://localhost:8080/api/disk/export/mydisk?format=vmdk"   # VMware
curl -O "http://localhost:8080/api/disk/export/mydisk?format=vdi"    # VirtualBox
curl -O "http://localhost:8080/api/disk/export/mydisk?format=vhdx"   # Hyper-V
curl -O "http://localhost:8080/api/disk/export/mydisk?format=raw"    # Raw image

SQLite with WAL mode. Tables:

# Pick your platform directory
cd linux   # or mac / windows
cargo build --release

# Run directly (development)
cargo run -- server 0.0.0.0:8080

vmcontrol/
├── src/                       # Rust source code
│   ├── main.rs                # CLI + server entry point
│   ├── server.rs              # Actix-web API routes & handlers
│   ├── operations.rs          # QEMU VM/disk operations
│   ├── db.rs                  # SQLite database layer
│   ├── config.rs              # YAML config loader
│   ├── models.rs              # Data structures (VmStartConfig, etc.)
│   ├── mds.rs                 # EC2-compatible metadata service
│   ├── api_helpers.rs         # QEMU monitor protocol (QMP)
│   ├── guest_agent.rs         # QEMU Guest Agent (QGA) protocol
│   ├── disk_edit.rs           # QCOW2 disk mount/browse/edit
│   └── ssh.rs                 # Command execution utilities
├── static/                    # Web UI (source of truth)
│   ├── index.html             # Control panel
│   ├── app.js                 # Frontend application
│   ├── style.css              # Styling
│   ├── vnc.html               # noVNC viewer + file transfer
│   └── vendor/novnc/          # Bundled noVNC library
├── mac/                       # macOS platform
│   ├── install.sh             # launchd installer
│   └── src/                   # macOS-specific config defaults
├── linux/                     # Linux platform
│   ├── install.sh             # systemd installer
│   └── src/                   # Linux-specific config defaults
├── windows/                   # Windows platform
│   ├── install.bat            # NSSM service installer
│   └── src/                   # Windows-specific config defaults
├── Cargo.toml                 # Package manifest (v0.3.0)
└── config.yaml                # Development config

MIT