Panel Virtual Machines

Panel Virtual Machines

Create, configure, start, inspect, stop and delete guests on the native Rust VM host. You can attach an existing installer ISO, choose a validated GPU passthrough group, and inspect guest serial output and live counters. The optional QEMU runner must be explicitly selected; it is not required for the native VM monitor.

Open System / VM hosting at /rust/system/vms. An administrator is required to see or change guest state. A non-administrator sees a read-only explanation with no VM forms. The page is server-rendered; the supervisor is the source of truth. No disk image is created automatically.

Before creating a guest

1. Under Host prerequisites, check KVM. A guest using KVM must have an accessible KVM device; GPU passthrough additionally requires KVM and a complete assignable IOMMU group.
2. Prepare an existing primary raw or qcow2 disk inside the displayed Images root; for installation also prepare an existing read-only ISO under that directory.
3. Prepare two existing firmware files: OVMF code firmware path (existing regular file) and OVMF variables template path (existing regular file). Direct kernel boot is an alternative only for the native monitor and requires a real kernel file.
4. Under VFIO GPU eligibility, read reasons for rejected adapters. Boot display adapters, incomplete groups and devices in use by the Panel engine are not offered as assignable choices.
5. Under Define guest, set Guest name (letters, digits, dash, underscore), vCPUs (1–64), RAM MiB (512–262144), Disk image path (raw/qcow2, must exist under Panel images root) and Disk format.
6. Set Runner to Lexi VM monitor (default), or QEMU (optional) if your installation supplies that runner. The native monitor requires Acceleration: KVM; software TCG can be explicitly selected only for an appropriate optional runner, and cannot use VFIO GPU passthrough.
7. Choose Network: User-mode NAT or Disconnected, and optionally enable Start automatically at supervisor startup. Choose VFIO GPU (only eligible IOMMU groups) when assigning an isolated group. Select Define guest to save without starting.

A running guest has Stop guest, which now requires ticking Confirm stopping this guest before the browser submits a stop request. The underlying authenticated VM API remains available to automation without that browser checkbox. The page shows missing live counter fields as Unavailable, never fabricated zeros; a failed metrics or console read is shown as an error. The guest also has Guest metrics, Live console (last 200 lines) and Send console input controls. The Serial log tail (last 30 lines, backend-bounded) remains available for stopped guests. Delete guest requires Confirm permanent deletion of this guest configuration and refuses running guests; deleting a definition does not remove disk images.

Guided task: create a VM with GPU passthrough and boot an installer ISO

1. From Guided VM tasks, select Open guided VM tasks to open /rust/system/vms/guides.
2. In 1. Create a guest with GPU and installer ISO, supply a fresh Guest name, Disk image path (existing), Installer ISO image path, both firmware paths, vCPUs (1–64) and RAM MiB (512–262144). Select VFIO GPU group from eligible options; this may encompass multiple PCI functions.
3. Select Prepare guest. The guided task refuses names of existing guests, missing installer images, inaccessible disk/firmware files and unsafe GPU groups; a successful result reports stage: prepared.
4. In Continue a prepared guest, enter Prepared guest name and select 2. Boot prepared guest. The supervisor checks KVM and device ownership again before starting; the result reports state: running only after a successful status check.
5. Select Inspect guest state and serial output. Complete the installer using the guest's serial interface. Guest state alone does not confirm installation success.
6. When installation is complete, use the normal Edit guest form to remove Optional ISO image path (raw, read-only, under images root) before booting the installed disk. Editing a guided guest outside the wizard invalidates its automatic undo safeguard; from then on, use normal VM controls.
7. To abandon the guided guest before editing it, choose Undo guided guest and tick Confirm removal of guided guest configuration; disks remain. Undo stops the guest if needed and removes only its saved definition, not any images.

Guided task: run a model server inside a VM

1. Open /rust/system/vms/guides and use 1. Create a guest with installed system disk. The Installed guest disk path must already contain a bootable operating system with the desired service installed; leave out installer media.
2. Enter Guest name, firmware paths, processor and memory settings, then select Prepare guest. This workflow uses the native VM monitor, KVM, and User-mode NAT by default.
3. Supply Prepared guest name and select 2. Boot prepared guest. Use Inspect guest state and serial output to confirm startup.
4. Sign in to the guest from its serial console using the System / VM hosting page. In the guided page, enter Service startup command (runs inside signed-in guest), tick I am signed in at the guest serial terminal, then select 3. Send guest service startup command. This delivers text plus a newline to the guest serial terminal; it never invokes a host shell. The service command is supplied by the operator because installation and invocation differ across guests.
5. Select Inspect guest state and serial output and verify in-guest startup logs and the service's own readiness indication. A submitted: true result only confirms the console accepted text, not that the service started or can accept network clients.
6. Once verification is finished, use Stop guest or, if you want to discard the unmodified guided configuration, Undo guided guest with confirmation. Images remain intact.

There is no automatic password entry, package installation, service probe or host port forwarding in the guide. To reach a service externally you must separately configure suitable networking in the guest and any required existing host forwarding settings; user-mode NAT alone is not evidence of externally reachable service endpoints.

Controls and tooltip reference

All listed native controls have a question-mark help marker; no classic VM controls exist, so no classic selectors are attached.

Control displayed	Registry ID	Tooltip
Host prerequisites	host	Shows host requirements; a missing acceleration device prevents accelerated guests from starting.
Guests	inventory	Lists saved guests, their running state, assigned disks and GPU groups, and available actions.
State	status	Shows the supervisor's current guest state, start time, exit code and elapsed runtime.
Guest name	name	Names the guest using letters, digits, dashes or underscores; changing a saved name requires a new guest.
vCPUs	cpus	Sets how many virtual processor cores the guest may use, from 1 to 64.
RAM MiB	memory	Sets guest memory in mebibytes, from 512 to 262144, subject to available host memory.
Disk image path	disk	Selects an existing guest disk image inside the Panel images directory; saving does not create a disk.
Disk format	disk-format	Specifies whether the existing primary disk uses raw or qcow2 storage format.
Optional ISO image path	iso	Attaches an existing installer image read-only; leave this blank when using an installed guest disk.
OVMF code firmware path	firmware-code	Locates an existing firmware code file required to boot the guest.
OVMF variables template path	firmware-vars	Locates the existing firmware variables file used to initialize the guest.
Runner	runner	Chooses the native Rust VM monitor or optional QEMU; monitor-only metrics and serial input need the native runner.
Direct-boot Linux kernel	kernel	Uses an existing kernel for direct boot instead of the usual firmware path where supported.
Direct-boot initrd	initrd	Attaches an optional initial memory image for direct kernel boot.
Direct-boot kernel command line	cmdline	Passes the supplied startup options verbatim to a direct-boot guest kernel.
Network	network	Enables guest user-mode network translation or disconnects the guest network.
Acceleration	accel	Uses KVM when available or explicitly selects software emulation; GPU passthrough requires KVM.
VFIO GPU	gpu	Assigns only a fully eligible non-boot IOMMU device group that the host workload is not using.
VFIO GPU eligibility	eligibility	Lists GPUs that cannot safely be passed through and the reason each group was refused.
Start automatically	autostart	Starts the saved guest when the supervisor starts; this is a persistent setting.
Allow removal of the existing GPU assignment	gpu-remove	Explicitly permits clearing a previously assigned GPU group while editing a guest.
Define guest	save	Validates and stores the guest definition without starting it or creating disk images.
Edit guest	edit	Changes an existing stopped guest without silently deleting advanced disk and forwarding settings.
Start guest	start	Starts a saved guest after checking disk, firmware, host acceleration and device ownership.
Stop guest	stop	Requests shutdown of a running guest; a guest that does not exit may be terminated.
Confirm guest stop	stop-confirm	Confirms interruption of the running guest before the browser sends a stop request.
Delete guest	delete	Deletes the saved configuration of a stopped guest after explicit confirmation; disk images remain.
Confirm permanent deletion	delete-confirm	Requires explicit permission before removing a stopped guest configuration.
Guest metrics	metrics	Displays available live processor, memory, storage and network counters for a running guest.
Live console	console	Displays up to 200 recent guest serial lines while the guest is running.
Send text to guest serial console	console-text	Sends text into the running guest terminal, which may execute it if a shell is active.
Send console input	console-send	Submits the serial text followed by a newline to the active native guest monitor.
Serial log tail	serial	Shows the last 30 bounded guest serial lines retained by the supervisor.
Guided VM tasks	guides	Opens controlled instructions for installer passthrough and running a service inside a guest.
Prepare guest	guide-prepare	Checks that this name is unused and saves a new guest through the supervisor without starting it.
Boot guided guest	guide-start	Starts only a guest prepared during this guided task; start can be reversed by stop.
Stop guided guest	guide-stop	Stops a tracked running guest and makes it eligible for another guided start or confirmed undo.
Send service command	guide-command	After guest sign-in is confirmed, sends the supplied command to the running guest serial terminal.
I am signed in at the guest serial terminal	guide-login-confirm	Confirms a guest shell is ready so submitted text is not sent to an unrelated login prompt.
Confirm removal of guided guest configuration	guide-undo-confirm	Authorizes deleting only the tracked and unchanged guest definition; disk images are not removed.
Inspect guided guest	guide-inspect	Checks the actual guest state and retrieves the latest available serial output.
Undo guided guest	guide-undo	Stops and deletes only the guest configuration tracked as created by this guided task; disks remain.

API operations

Method	Registered route	Operator-facing use
GET	/api/system/vms	Saved guest definitions and native guest list
GET	/api/system/vms/status	State, exit data and bounded serial tail
GET	/api/system/vms/metrics	Live metrics for a running guest; native monitor support required
GET	/api/system/vms/console	Guest serial tail, 1–200 lines
POST	/api/system/vms/save	Define or edit guest through schema validation
POST	/api/system/vms/start	Start after host and GPU safety checks
POST	/api/system/vms/stop	Stop a running guest
POST	/api/system/vms/delete	Delete a stopped guest configuration
POST	/api/system/vms/console-input	Deliver at most 4096 bytes to a running native monitor guest
POST	/api/ux/vms/guides/prepare	Create an unused guest tracked for safe undo
POST	/api/ux/vms/guides/start	Start a tracked guest and verify running status
POST	/api/ux/vms/guides/command	Send signed-in guest's supplied service command
GET or POST	/api/ux/vms/guides/inspect	Read a tracked guest's state and serial tail
POST	/api/ux/vms/guides/undo	Stop and remove an unchanged tracked guest definition, never its disk

Every guided API route enforces administrator permission. Guided progress is in-memory per authenticated operator, Panel directory and guest name; after a supervisor restart or an out-of-guide configuration edit, use the regular VM page to inspect and manage the guest safely. Guided actions do not have a command-line equivalent in this release.

Related guides: Panel Instances, Panel Power and Hardware, Reference Guided Tasks.