š„ļø Virtual Machines
The Virtual Machines tab is the default view. It shows all your VMs as cards.
Summary Bar
At the top, four summary tiles show the total count of VMs in each state at a glance:
- Total ā all VMs
- Running ā currently active
- Stopped ā powered off
- Paused / Suspended ā frozen or saved to disk
Search, Filter & Sort
Above the VM grid, a toolbar lets you narrow down the list:
- Search ā type any part of a VM name to filter cards instantly
- State pills ā click All, Running, Stopped, or Paused to show only VMs in that state
- Sort ā choose Name AāZ, Name ZāA, or By State
Filters and sorting are preserved during auto-refresh.
Grid and List View
Use the ā / ā” toggle buttons in the toolbar to switch between the default card grid and a compact table view. The table view shows all VMs in a single scrollable list with columns for name, distro, status, CPU/RAM, and uptime ā useful when you have many VMs. Your preference is saved and remembered across sessions.
Creating VMs
The toolbar provides two ways to create a virtual machine ā a quick path for getting started fast, and a full-featured dialog for complete control over hardware configuration.
Quick Create
Click the ļ¼ Quick VM button on the left side of the toolbar to open the Quick Create dialog ā a streamlined form covering only the essentials.
| Field | Description |
|---|---|
| Name | A unique name ā auto-generated on open, or type your own |
| OS | Linux or macOS (macOS requires Apple Silicon) |
| CPU cores | Number of virtual CPUs (minimum 1) |
| Memory | RAM in MB ā a live hint shows the equivalent in GB |
| Disk (GB) | Size of the primary virtual disk |
| Image | Select from all ISO or IPSW files in the VirtualProg images folder |
The Image dropdown automatically shows only files relevant to the selected OS ā ISO files for Linux and IPSW files for macOS. Known images are displayed with their friendly name and alias (e.g. Ubuntu 26.04 LTS (ubuntu)); any files you have placed directly in the images folder appear by filename.
Click Create VM to submit. The VM is created in the background ā a toast notification confirms success, and the VM list refreshes automatically.
Create Virtual Machine
Click the ā New VM button to open the full Create Virtual Machine dialog. This gives you complete control over every aspect of the new VM's hardware.
The dialog is organised into sections accessible from the sidebar on the left. The VM name in the title bar updates live as you type.
Sidebar sections
| Section | What you configure |
|---|---|
| General | Name, OS, distro/version, notes, headless mode, full screen, nested virtualisation, entropy |
| Resources | CPU core count, memory (MB), memory balloon |
| Display | Resolution mode (auto / force), width, height, PPI |
| Sound | Audio input and output device toggles |
| Input Devices (macOS only) | Keyboard and mouse device type ā choose Mac for modern guests or Legacy for Monterey |
| Startup & Shutdown | Auto-start, startup delay, host sleep / shutdown / window-close behaviour, AutoPause |
| Image (macOS only) | IPSW restore image to attach |
| Rosetta (Linux only) | Enable Rosetta translation layer for running x86_64 binaries on Apple Silicon Linux guests |
| Boot Disk | Select which disk or CD/DVD the VM boots from ā options update automatically as you add or remove devices |
| Security | Password protection (set, change, or remove the VM password), clipboard sharing, screenshot, screen recording, and dashboard log access controls |
| Auto Snapshots | Automatic snapshot schedule ā prefix, type (On Start, Daily, Weekly, Monthly, On Shutdown), and maximum snapshots to keep |
| Schedule | Automatic start and stop times by day of week |
| Webhooks | HTTP POST notifications sent to external URLs whenever this VM changes state |
| Disk 1 ā¦ N | Size, interface (VirtIo / NVME), type (Dynamic / Fixed), cache mode (Auto / Cached / Uncached), sync mode (Full / FSync / None) |
| Network 1 ā¦ N | Type (NAT, bridged, or custom), MAC address, static IP suffix, port forwarding rules |
| Network Block Device 1 ā¦ N | URL of the remote NBD block device to attach |
| CD/DVD 1 ā¦ N | ISO image to mount as a virtual optical drive (available for both Linux and macOS VMs) |
| Serial Port 1 ā¦ N | Serial port mode (Console / Pipe / File), path, and terminal theme |
Adding and removing devices
Use the ļ¼ button at the bottom of the sidebar to add a disk, network, Network Block Device, CD/DVD, or serial port. Select an entry and click the š button to remove it. At least one disk and one network are required.
Custom networks
When Custom is selected as the network type, a Static IP field appears. Entering a suffix (2ā254) assigns a fixed address to the VM on that network. With a static IP configured, a Port Forwarding table also appears ā add rules to map host ports to guest ports over TCP or UDP.
Click Create VM to submit. Use vpvm images get <alias> or the Image Catalog to download boot images if the image list is empty.
VM Cards
Each card shows the VM name, OS/distro, current state, CPU, and memory. Action buttons are shown directly on the card and update based on the VM state:
| State | Available Actions |
|---|---|
| Stopped | ā¶ Start, āļø Configure, š Delete |
| Running | ā Shutdown, ā» Stop, āø Pause, āŗ Restart, š¾ Suspend, š„ Connect (non-headless only) |
| Paused / Suspended | ā¶ Resume |
The āļø Configure button opens the full Create Virtual Machine dialog pre-populated with the VM's current settings, letting you edit all hardware and behaviour fields. In edit mode:
- Name ā the name field is editable; changing it renames the VM when you save
- Disks ā shown read-only (size and type cannot be changed on an existing VM)
- Networks ā fully editable, including static IP, port forwarding rules, and adding new networks
- All other sections (Display, Sound, Startup & Shutdown, AutoPause, Auto Snapshots, Schedule, Webhooks, Boot Disk, Security, Serial Ports, Network Block Devices, CD/DVDs, Input Devices, Rosetta) are fully editable
Running VMs show ā¶ Running for Xh Ym on the card so you can see at a glance how long a VM has been up.
Password-protected VMs display a š badge on their card (grid view) or beside their name (list view) so you can identify them at a glance.
Password-Protected VMs
When a VM has password protection enabled, actions that control or modify it are gated behind an unlock step.
| View | Indicator |
|---|---|
| Card grid | š badge in the card header |
| List view | š icon beside the VM name |
| Stopped VM Start button | Shows as š Unlock & Start |
Clicking any protected action ā Start, Configure, Delete, Clone, or Rename ā on a locked VM opens the Unlock dialog before the action runs.
Unlock Dialog
Enter the VM password and click Unlock (or press Enter). If the password is incorrect, an error message is shown and you can try again. Once accepted, the original action executes immediately.
Locking and Unlocking via Web CLI
You can also manage the lock state directly from the Web CLI Terminal:
Unlocks the VM for the current session. Control operations (start, stop, etc.) and configuration changes are permitted until the VM stops or is explicitly re-locked.
Re-locks the VM immediately without stopping it. The password is required again for any subsequent protected action.
Only VMs with a password configured can be locked. Attempting to lock a VM with no password returns an error.
Bulk Actions
You can act on multiple VMs at once:
- Hover a card to reveal its checkbox, then check the VMs you want to select. In list view, checkboxes are always visible.
- A bar slides up from the bottom showing how many VMs are selected, with Start, Shutdown, Stop, and Clear buttons.
- Actions are smart ā Start only applies to stopped or suspended VMs; Shutdown and Stop only apply to running VMs.
VM Detail Panel
Click any VM card to open the detail panel on the right. It shows full configuration and hardware details and uptime statistics.
From the detail panel you can also:
āļø
| Action | Description |
|---|---|
| š¦ Create Template | Save a stopped VM as a reusable template |
| š§¬ Clone | Duplicate a stopped VM under a new name |
| āļø Rename | Rename the VM ā enter the new name in the dialog |
| š„ Connect | Remote Control the VM from your browser |
Console Ports
If a VM has one or more serial ports configured in Console mode, a Console Ports section appears in the detail panel. Each port shows an Open Web Console button that launches the browser-based terminal for that port.
To configure a serial port as a console port, open the VM configuration in the VirtualProg app, go to Serial Ports, and set the mode to Console.
Memory Balloon
When a running Linux VM has Memory Balloon enabled, a Memory Balloon section appears at the bottom of the detail panel. This is particularly useful for headless VMs that do not have a remote control screen open.
| Field | Description |
|---|---|
| Configured | The total memory allocated to the VM |
| Target | The current balloon target ā memory actively available to the guest |
| Reclaimed | Memory returned to the host (Configured minus Target) |
Use the slider to set a new target, then click Apply. Click Reset to Max to return the target to the full configured amount.
Memory Balloon must be enabled in the VM's Resources configuration and the
virtio-balloondriver must be loaded in the guest. The section is hidden when the VM is stopped or when balloon is not available.
Auto-Refresh
The dashboard refreshes automatically in the background. Use the āŗ Refresh button in the header to refresh immediately.
To change the refresh interval, click the ā icon in the header and choose from 5 seconds up to 5 minutes, or select Manual only to disable auto-refresh entirely. Your preference is saved across sessions.