vm.create ========= Create a Virtual Machine (VM). Maximum of 16 guest virtual CPUs are allowed. By default, every virtual CPU is configured as a separate package. Multiple cores can be configured per CPU by specifying `cores` attributes. `vcpus` specifies total number of CPU sockets. `cores` specifies number of cores per socket. `threads` specifies number of threads per core. `ensure_display_device` when set ( the default ) will ensure that the guest always has access to a video device. For headless installations like ubuntu server this is required for the guest to operate properly. However for cases where consumer would like to use GPU passthrough and does not want a display device added should set this to `false`. `arch_type` refers to architecture type and can be specified for the guest. By default the value is `null` and system in this case will choose a reasonable default based on host. `machine_type` refers to machine type of the guest based on the architecture type selected with `arch_type`. By default the value is `null` and system in this case will choose a reasonable default based on `arch_type` configuration. `shutdown_timeout` indicates the time in seconds the system waits for the VM to cleanly shutdown. During system shutdown, if the VM hasn't exited after a hardware shutdown signal has been sent by the system within `shutdown_timeout` seconds, system initiates poweroff for the VM to stop it. `hide_from_msr` is a boolean which when set will hide the KVM hypervisor from standard MSR based discovery and is useful to enable when doing GPU passthrough. `hyperv_enlightenments` can be used to enable subset of predefined Hyper-V enlightenments for Windows guests. These enlightenments improve performance and enable otherwise missing features. `suspend_on_snapshot` is a boolean attribute which when enabled will automatically pause/suspend VMs when a snapshot is being taken for periodic snapshot tasks. For manual snapshots, if user has specified vms to be paused, they will be in that case. .. raw:: html
Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: vm_create

vm_create

Type: object

VMCreateArgs parameters.

 No Additional Properties

Command Line Args

Type: string Default: ""

Additional command line arguments passed to the VM hypervisor.

Cpu Mode

Type: enum (of string) Default: "CUSTOM"

CPU virtualization mode.

  • CUSTOM: Use specified model.
  • HOST-MODEL: Mirror host CPU.
  • HOST-PASSTHROUGH: Provide direct access to host CPU features.
Must be one of:
  • "CUSTOM"
  • "HOST-MODEL"
  • "HOST-PASSTHROUGH"

Cpu Model

Default: null

Specific CPU model to emulate. null to use hypervisor default.

Type: string
Type: null

Name

Type: string

Display name of the virtual machine.

Must be at least 1 characters long

Description

Type: string Default: ""

Optional description or notes about the virtual machine.

Vcpus

Type: integer Default: 1

Number of virtual CPUs allocated to the VM.

Value must be greater or equal to 1

Cores

Type: integer Default: 1

Number of CPU cores per socket.

Value must be greater or equal to 1

Threads

Type: integer Default: 1

Number of threads per CPU core.

Value must be greater or equal to 1

Cpuset

Default: null

Set of host CPU cores to pin VM CPUs to. null for no pinning.

Type: string
Type: null

Nodeset

Default: null

Set of NUMA nodes to constrain VM memory allocation. null for no constraints.

Type: string
Type: null

Enable Cpu Topology Extension

Type: boolean Default: false

Whether to expose detailed CPU topology information to the guest OS.

Pin Vcpus

Type: boolean Default: false

Whether to pin virtual CPUs to specific host CPU cores. Improves performance but reduces host flexibility.

Suspend On Snapshot

Type: boolean Default: false

Whether to suspend the VM when taking snapshots.

Trusted Platform Module

Type: boolean Default: false

Whether to enable virtual Trusted Platform Module (TPM) for the VM.

Memory

Type: integer

Amount of memory allocated to the VM in megabytes.

Value must be greater or equal to 20

Min Memory

Default: null

Minimum memory allocation for dynamic memory ballooning in megabytes. Allows VM memory to shrink during low usage but guarantees this minimum. null to disable ballooning.

Type: integer

Value must be greater or equal to 20

Type: null

Hyperv Enlightenments

Type: boolean Default: false

Whether to enable Hyper-V enlightenments for improved Windows guest performance.

Bootloader

Type: enum (of string) Default: "UEFI"

Boot firmware type. UEFI for modern UEFI, UEFI_CSM for legacy BIOS compatibility.

Must be one of:
  • "UEFI_CSM"
  • "UEFI"

Bootloader Ovmf

Default: null

OVMF firmware file to use for UEFI boot.

Type: string
Type: null

Examples:

"OVMF_CODE.fd"
    
"OVMF_CODE.secboot.fd"

Autostart

Type: boolean Default: true

Whether to automatically start the VM when the host system boots.

Hide From Msr

Type: boolean Default: false

Whether to hide hypervisor signatures from guest OS MSR access.

Ensure Display Device

Type: boolean Default: true

Whether to ensure at least one display device is configured for the VM.

Time

Type: enum (of string) Default: "LOCAL"

Guest OS time zone reference. LOCAL uses host timezone, UTC uses coordinated universal time.

Must be one of:
  • "LOCAL"
  • "UTC"

Shutdown Timeout

Type: integer Default: 90

Maximum time in seconds to wait for graceful shutdown before forcing power off. Default 90s balances allowing sufficient time for clean shutdown while avoiding indefinite hangs.

Value must be greater or equal to 5 and lesser or equal to 300

Arch Type

Default: null

Guest architecture type. null to use hypervisor default.

Type: string
Type: null

Machine Type

Default: null

Virtual machine type/chipset. null to use hypervisor default.

Type: string
Type: null

Uuid

Default: null

Unique UUID for the VM. null to auto-generate.

Type: string
Type: null

Enable Secure Boot

Type: boolean Default: false

Whether to enable UEFI Secure Boot for enhanced security.

VMEntry

Type: object

The newly created virtual machine configuration.

 No Additional Properties

Command Line Args

Type: string Default: ""

Additional command line arguments passed to the VM hypervisor.

Cpu Mode

Type: enum (of string) Default: "CUSTOM"

CPU virtualization mode.

  • CUSTOM: Use specified model.
  • HOST-MODEL: Mirror host CPU.
  • HOST-PASSTHROUGH: Provide direct access to host CPU features.
Must be one of:
  • "CUSTOM"
  • "HOST-MODEL"
  • "HOST-PASSTHROUGH"

Cpu Model

Default: null

Specific CPU model to emulate. null to use hypervisor default.

Type: string
Type: null

Name

Type: string

Display name of the virtual machine.

Must be at least 1 characters long

Description

Type: string Default: ""

Optional description or notes about the virtual machine.

Vcpus

Type: integer Default: 1

Number of virtual CPUs allocated to the VM.

Value must be greater or equal to 1

Cores

Type: integer Default: 1

Number of CPU cores per socket.

Value must be greater or equal to 1

Threads

Type: integer Default: 1

Number of threads per CPU core.

Value must be greater or equal to 1

Cpuset

Default: null

Set of host CPU cores to pin VM CPUs to. null for no pinning.

Type: string
Type: null

Nodeset

Default: null

Set of NUMA nodes to constrain VM memory allocation. null for no constraints.

Type: string
Type: null

Enable Cpu Topology Extension

Type: boolean Default: false

Whether to expose detailed CPU topology information to the guest OS.

Pin Vcpus

Type: boolean Default: false

Whether to pin virtual CPUs to specific host CPU cores. Improves performance but reduces host flexibility.

Suspend On Snapshot

Type: boolean Default: false

Whether to suspend the VM when taking snapshots.

Trusted Platform Module

Type: boolean Default: false

Whether to enable virtual Trusted Platform Module (TPM) for the VM.

Memory

Type: integer

Amount of memory allocated to the VM in megabytes.

Value must be greater or equal to 20

Min Memory

Default: null

Minimum memory allocation for dynamic memory ballooning in megabytes. Allows VM memory to shrink during low usage but guarantees this minimum. null to disable ballooning.

Type: integer

Value must be greater or equal to 20

Type: null

Hyperv Enlightenments

Type: boolean Default: false

Whether to enable Hyper-V enlightenments for improved Windows guest performance.

Bootloader

Type: enum (of string) Default: "UEFI"

Boot firmware type. UEFI for modern UEFI, UEFI_CSM for legacy BIOS compatibility.

Must be one of:
  • "UEFI_CSM"
  • "UEFI"

Bootloader Ovmf

Type: string Default: "OVMF_CODE.fd"

OVMF firmware file to use for UEFI boot.
Examples:

"OVMF_CODE.fd"
    
"OVMF_CODE.secboot.fd"

Autostart

Type: boolean Default: true

Whether to automatically start the VM when the host system boots.

Hide From Msr

Type: boolean Default: false

Whether to hide hypervisor signatures from guest OS MSR access.

Ensure Display Device

Type: boolean Default: true

Whether to ensure at least one display device is configured for the VM.

Time

Type: enum (of string) Default: "LOCAL"

Guest OS time zone reference. LOCAL uses host timezone, UTC uses coordinated universal time.

Must be one of:
  • "LOCAL"
  • "UTC"

Shutdown Timeout

Type: integer Default: 90

Maximum time in seconds to wait for graceful shutdown before forcing power off. Default 90s balances allowing sufficient time for clean shutdown while avoiding indefinite hangs.

Value must be greater or equal to 5 and lesser or equal to 300

Arch Type

Default: null

Guest architecture type. null to use hypervisor default.

Type: string
Type: null

Machine Type

Default: null

Virtual machine type/chipset. null to use hypervisor default.

Type: string
Type: null

Uuid

Default: null

Unique UUID for the VM. null to auto-generate.

Type: string
Type: null

Devices

Type: array of object

Array of virtual devices attached to this VM.

 No Additional Items
Each item of this array must be:

VMDeviceEntry

Type: object
No Additional Properties

Id

Type: integer

Unique identifier for the VM device.

Attributes


Device-specific configuration attributes.

VMCDROMDevice

Type: object
No Additional Properties

Dtype

Type: const

Device type identifier for CD-ROM/DVD devices.

Specific value: "CDROM"

Path

Type: string Default: "*"

Path must not contain "{", "}" characters, and it should start with "/mnt/".

Must match regular expression: ^[^{}]*$

Must be at least 1 characters long

VMDisplayDevice

Type: object
No Additional Properties

Dtype

Type: const

Device type identifier for display/graphics devices.

Specific value: "DISPLAY"

Resolution

Type: enum (of string) Default: "1024x768"

Screen resolution for the virtual display.

Must be one of:
  • "1920x1200"
  • "1920x1080"
  • "1600x1200"
  • "1600x900"
  • "1400x1050"
  • "1280x1024"
  • "1280x720"
  • "1024x768"
  • "800x600"
  • "640x480"

Port

Default: null

VNC/SPICE port number for remote display access. null for auto-assignment.

Type: integer

Value must be greater or equal to 5900 and lesser or equal to 65535

Type: null

Web Port

Default: null

Web-based display access port number. null for auto-assignment.

Type: integer
Type: null

Bind

Type: string Default: "127.0.0.1"

IP address to bind the display server to.

Must be at least 1 characters long

Wait

Type: boolean Default: false

Whether to wait for a client connection before starting the VM.

Password

Default: null

Password for display server authentication.

Type: string
Type: null

Web

Type: boolean Default: true

Whether to enable web-based display access.

Type

Type: enum (of string) Default: "SPICE"

Display protocol type.

Must be one of:
  • "SPICE"
  • "VNC"

VMNICDevice

Type: object
No Additional Properties

Dtype

Type: const

Device type identifier for network interface cards.

Specific value: "NIC"

Trust Guest Rx Filters

Type: boolean Default: false

Whether to trust guest OS receive filter settings for better performance.

Type

Type: enum (of string) Default: "E1000"

Network interface controller type. E1000 for Intel compatibility, VIRTIO for performance.

Must be one of:
  • "E1000"
  • "VIRTIO"

Nic Attach

Default: null

Host network interface or bridge to attach to. null for no attachment.

Type: string
Type: null

Mac

Default: null

MAC address for the virtual network interface. null for auto-generation.

Type: string
Must match regular expression: ^([0-9A-Fa-f]{2}[:-]?){5}([0-9A-Fa-f]{2})$
Type: null

VMPCIDevice

Type: object
No Additional Properties

Dtype

Type: const

Device type identifier for PCI passthrough devices.

Specific value: "PCI"

Pptdev

Type: string

Host PCI device identifier to pass through to the VM.

Must be at least 1 characters long

VMRAWDevice

Type: object
No Additional Properties

Dtype

Type: const

Device type identifier for raw disk devices.

Specific value: "RAW"

Path

Type: string Default: "127.0.0.1"

Path must not contain "{", "}" characters.

Must match regular expression: ^[^{}]*$

Must be at least 1 characters long

Type

Type: enum (of string) Default: "AHCI"

Disk controller interface type. AHCI for compatibility, VIRTIO for performance.

Must be one of:
  • "AHCI"
  • "VIRTIO"

Exists

Type: boolean Default: false

Whether the disk file already exists or should be created.

Boot

Type: boolean Default: false

Whether this disk should be marked as bootable.

Size

Default: null

Size of the disk in bytes. Required if creating a new disk file.

Type: integer
Type: null

Logical Sectorsize

Default: null

Logical sector size for the disk. null for default.

Type: enum (of integer or null)
Must be one of:
  • null
  • 512
  • 4096
Type: null

Physical Sectorsize

Default: null

Physical sector size for the disk. null for default.

Type: enum (of integer or null)
Must be one of:
  • null
  • 512
  • 4096
Type: null

Iotype

Type: enum (of string) Default: "THREADS"

I/O backend type for disk operations.

Must be one of:
  • "NATIVE"
  • "THREADS"
  • "IO_URING"

Serial

Default: null

Serial number to assign to the virtual disk. null for auto-generated.

Type: string

Must be at least 1 characters long

Type: null

VMDiskDevice

Type: object
No Additional Properties

Dtype

Type: const

Device type identifier for virtual disk devices.

Specific value: "DISK"

Path

Default: null

Path to existing disk file or ZFS volume. null if creating a new ZFS volume.

Type: string

Must be at least 1 characters long

Type: null

Type

Type: enum (of string) Default: "AHCI"

Disk controller interface type. AHCI for compatibility, VIRTIO for performance.

Must be one of:
  • "AHCI"
  • "VIRTIO"

Create Zvol

Type: boolean Default: false

Whether to create a new ZFS volume for this disk.

Zvol Name

Default: null

Name for the new ZFS volume. Required if create_zvol is true.

Type: string
Type: null

Zvol Volsize

Default: null

Size of the new ZFS volume in bytes. Required if create_zvol is true.

Type: integer
Type: null

Logical Sectorsize

Default: null

Logical sector size for the disk. null for default.

Type: enum (of integer or null)
Must be one of:
  • null
  • 512
  • 4096
Type: null

Physical Sectorsize

Default: null

Physical sector size for the disk. null for default.

Type: enum (of integer or null)
Must be one of:
  • null
  • 512
  • 4096
Type: null

Iotype

Type: enum (of string) Default: "THREADS"

I/O backend type for disk operations.

Must be one of:
  • "NATIVE"
  • "THREADS"
  • "IO_URING"

Serial

Default: null

Serial number to assign to the virtual disk. null for auto-generated.

Type: string

Must be at least 1 characters long

Type: null

VMUSBDevice

Type: object
No Additional Properties

Dtype

Type: const

Device type identifier for USB devices.

Specific value: "USB"

Default: null

USB device attributes for identification. null for USB host controller only.

USBAttributes

Type: object
No Additional Properties

Vendor Id

Type: string Default: "127.0.0.1"

USB vendor identifier in hexadecimal format (e.g., '0x1d6b' for Linux Foundation).

Must match regular expression: ^0x.*

Must be at least 1 characters long

Product Id

Type: string Default: "127.0.0.1"

USB product identifier in hexadecimal format (e.g., '0x0002' for 2.0 root hub).

Must match regular expression: ^0x.*

Must be at least 1 characters long

Type: null

Controller Type

Type: enum (of string) Default: "nec-xhci"

USB controller type for the virtual machine.

Must be one of:
  • "piix3-uhci"
  • "piix4-uhci"
  • "ehci"
  • "ich9-ehci1"
  • "vt82c686b-uhci"
  • "pci-ohci"
  • "nec-xhci"
  • "qemu-xhci"

Device

Default: null

Host USB device path to pass through. null for controller only.

Type: string

Must be at least 1 characters long

Type: null

Vm

Type: integer

ID of the virtual machine this device belongs to.

Order

Type: integer

Boot order priority for this device (lower numbers boot first).

Display Available

Type: boolean

Whether at least one display device is available for this VM.

Id

Type: integer

Unique identifier for the virtual machine.

VMStatus

Type: object

Current runtime status information for the VM.

 No Additional Properties

State

Type: string Default: "127.0.0.1"

Current state of the virtual machine.

Must be at least 1 characters long


Examples:

"RUNNING"
    
"STOPPED"
    
"SUSPENDED"

Pid


Process ID of the running VM. null if not running.

Type: integer
Type: null

Domain State


Hypervisor-specific domain state.

Type: string

Must be at least 1 characters long

Type: null

Enable Secure Boot

Type: boolean Default: false

Whether to enable UEFI Secure Boot for enhanced security.


*Required roles:* VM_WRITE