# virt.instance.create

Create a new virtualized instance.

This method is a job.

Type: object

##

Type: array
No Additional Items

#### Tuple Validation

##### Parameter 1: virt_instance_create

#### virt_instance_create

Type: object

VirtInstanceCreateArgs parameters.

No Additional Properties

##

#### Name

Type: string

Name for the new virtual instance.

Must be at least `1` characters long

Must be at most `200` characters long

##

#### Source Type

Type: const Default: "IMAGE"

Source type for instance creation.

Specific value: `"IMAGE"`

##

#### Storage Pool

Default: null

Storage pool under which to allocate root filesystem. Must be one of the pools listed in virt.global.config output under "storage_pools". If None (default) then the pool specified in the global configuration will be used.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Image

Type: string

Image identifier to use for creating the instance.

Must be at least `1` characters long

Must be at most `200` characters long

##

#### Root Disk Size

Type: integer Default: 10

This can be specified when creating VMs so the root device's size can be configured. Root device for VMs is a sparse zvol and the field specifies space in GBs and defaults to 10 GBs.

Value must be greater or equal to `5`

##

#### Root Disk Io Bus

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

I/O bus type for the root disk (defaults to NVME for best performance).

##### Must be one of:

- "NVME"
- "VIRTIO-BLK"
- "VIRTIO-SCSI"

##

#### Remote

Type: const Default: "LINUX_CONTAINERS"

Remote image source to use.

Specific value: `"LINUX_CONTAINERS"`

##

#### Instance Type

Type: const Default: "CONTAINER"

Type of instance to create.

Specific value: `"CONTAINER"`

##

#### Environment

Default: null

Environment variables to set inside the instance.

## Any of

Type: object

##

Each additional property must conform to the following schema

Type: string
Type: null

##

#### Autostart

Default: true

Whether the instance should automatically start when the host boots.

## Any of

Type: boolean
Type: null

##

#### Cpu

Default: null

CPU allocation specification or `null` for automatic allocation.

## Any of

Type: string
Type: null

##

#### Devices

Default: null

Array of devices to attach to the instance.

## Any of

Type: array
No Additional Items

##### Each item of this array must be:

## One of

#### Disk

Type: object
No Additional Properties

##

#### Name

Default: null

Optional human-readable name for the virtualization device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Description

Default: null

Optional description explaining the purpose or configuration of this device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

##

#### Dev Type

Type: const

Device type identifier for virtual disk devices.

Specific value: `"DISK"`

##

#### Source

Default: null

For CONTAINER instances, this would be a valid pool path. For VM instances, it can be a valid zvol path or an incus storage volume name.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Destination

Default: null

Target path where the disk appears inside the virtualized instance.

## Any of

Type: string
Type: null

##

#### Boot Priority

Default: null

Boot priority for this disk device. Lower numbers boot first. `null` means non-bootable.

## Any of

Type: integer

Value must be greater or equal to `0`

Type: null

##

#### Io Bus

Type: enum (of null or string) Default: null

Storage bus type for optimal performance and compatibility.

##### Must be one of:

- "NVME"
- "VIRTIO-BLK"
- "VIRTIO-SCSI"
- null

##

#### Storage Pool

Default: null

Storage pool in which the device is located. This must be one of the storage pools listed in virt.global.config output.
If this is set to None during device creation, then the default storage pool defined in virt.global.config will be used.

## Any of

Type: string

Must be at least `1` characters long

Type: null

#### GPU

Type: object
No Additional Properties

##

#### Name

Default: null

Optional human-readable name for the virtualization device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Description

Default: null

Optional description explaining the purpose or configuration of this device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

##

#### Dev Type

Type: const

Device type identifier for graphics processing units.

Specific value: `"GPU"`

##

#### Gpu Type

Type: enum (of string)

Type of GPU virtualization (physical passthrough, mediated device, etc.).

##### Must be one of:

- "PHYSICAL"
- "MDEV"
- "MIG"
- "SRIOV"

##

#### Id

Default: null

Unique identifier for the GPU device.

## Any of

Type: string
Type: null

##

#### Gid

Default: null

Group ID for device permissions inside the container.

## Any of

Type: integer

Value must be greater or equal to `0` and lesser or equal to `90000000`

Type: null

##

#### Uid

Default: null

User ID for device permissions inside the container.

## Any of

Type: integer

Value must be greater or equal to `0` and lesser or equal to `90000000`

Type: null

##

#### Mode

Default: null

Permission mode for device access (e.g., '660').

## Any of

Type: string
Type: null

##

#### Mdev

Default: null

Mediated device identifier for GPU virtualization.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Mig Uuid

Default: null

Multi-Instance GPU UUID for NVIDIA GPU partitioning.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Pci

Default: null

PCI address of the GPU device on the host system.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Productid

Default: null

Product identifier for GPU device matching.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Vendorid

Default: null

Vendor identifier for GPU device matching.

## Any of

Type: string

Must be at least `1` characters long

Type: null

#### Proxy

Type: object
No Additional Properties

##

#### Name

Default: null

Optional human-readable name for the virtualization device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Description

Default: null

Optional description explaining the purpose or configuration of this device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

##

#### Dev Type

Type: const

Device type identifier for network port forwarding.

Specific value: `"PROXY"`

##

#### Source Proto

Type: enum (of string)

Network protocol (TCP or UDP) for the source connection.

##### Must be one of:

- "UDP"
- "TCP"

##

#### Source Port

Type: integer

Source port number on the host system to forward from.

Value must be greater or equal to `1` and lesser or equal to `65535`

##

#### Dest Proto

Type: enum (of string)

Network protocol (TCP or UDP) for the destination connection.

##### Must be one of:

- "UDP"
- "TCP"

##

#### Dest Port

Type: integer

Destination port number inside the virtualized instance.

Value must be greater or equal to `1` and lesser or equal to `65535`

#### TPM

Type: object
No Additional Properties

##

#### Name

Default: null

Optional human-readable name for the virtualization device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Description

Default: null

Optional description explaining the purpose or configuration of this device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

##

#### Dev Type

Type: const

Device type identifier for Trusted Platform Module devices.

Specific value: `"TPM"`

##

#### Path

Default: null

Path to the TPM device on the host system.

## Any of

Type: string
Type: null

##

#### Pathrm

Default: null

Resource manager path for TPM device access.

## Any of

Type: string
Type: null

#### USB

Type: object
No Additional Properties

##

#### Name

Default: null

Optional human-readable name for the virtualization device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Description

Default: null

Optional description explaining the purpose or configuration of this device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

##

#### Dev Type

Type: const

Device type identifier for USB devices.

Specific value: `"USB"`

##

#### Bus

Default: null

USB bus number on the host system.

## Any of

Type: integer
Type: null

##

#### Dev

Default: null

USB device number on the specified bus.

## Any of

Type: integer
Type: null

##

#### Product Id

Default: null

USB product identifier for device matching.

## Any of

Type: string
Type: null

##

#### Vendor Id

Default: null

USB vendor identifier for device matching.

## Any of

Type: string
Type: null

#### NIC

Type: object
No Additional Properties

##

#### Name

Default: null

Optional human-readable name for the virtualization device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Description

Default: null

Optional description explaining the purpose or configuration of this device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

##

#### Dev Type

Type: const

Device type identifier for network interface cards.

Specific value: `"NIC"`

##

#### Network

Default: null

Name of the network to connect this NIC to.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Nic Type

Default: null

Type of network interface (bridged or macvlan).

## Any of

Type: enum (of string)

##### Must be one of:

- "BRIDGED"
- "MACVLAN"

Type: null

##

#### Parent

Default: null

Parent network interface on the host system.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Mac

Default: null

MAC address for the virtual network interface. `null` for auto-generated.

## Any of

Type: string
Type: null

#### PCI

Type: object
No Additional Properties

##

#### Name

Default: null

Optional human-readable name for the virtualization device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Description

Default: null

Optional description explaining the purpose or configuration of this device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

##

#### Dev Type

Type: const

Device type identifier for PCI device passthrough.

Specific value: `"PCI"`

##

#### Address

Type: string

PCI bus address of the device to pass through to the virtualized instance.

Must be at least `1` characters long

#### CDROM

Type: object
No Additional Properties

##

#### Name

Default: null

Optional human-readable name for the virtualization device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Description

Default: null

Optional description explaining the purpose or configuration of this device.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

##

#### Dev Type

Type: const

Device type identifier for CD-ROM/DVD optical drives.

Specific value: `"CDROM"`

##

#### Source

Type: string

Path to the ISO image file or physical optical drive to mount.

Must be at least `1` characters long

##

#### Boot Priority

Default: null

Boot priority for this optical device. Lower numbers boot first. `null` means non-bootable.

## Any of

Type: integer

Value must be greater or equal to `0`

Type: null
Type: null

##

#### Memory

Default: null

Memory allocation in bytes or `null` for automatic allocation.

## Any of

Type: integer
Type: null

##

#### Privileged Mode

Type: boolean Default: false

This is only valid for containers and should only be set when container instance which is to be deployed is to run in a privileged mode.

##

#### VirtInstanceEntry

Type: object

The created virtual instance configuration.

No Additional Properties

##

#### Id

Type: string

Unique identifier for the virtual instance.

##

#### Name

Type: string

Human-readable name for the virtual instance.

Must be at least `1` characters long

Must be at most `200` characters long

##

#### Type

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

Type of virtual instance.

##### Must be one of:

- "CONTAINER"
- "VM"

##

#### Status

Type: enum (of string)

Current operational status of the virtual instance.

##### Must be one of:

- "RUNNING"
- "STOPPED"
- "UNKNOWN"
- "ERROR"
- "FROZEN"
- "STARTING"
- "STOPPING"
- "FREEZING"
- "THAWED"
- "ABORTING"

##

#### Cpu

CPU configuration string or `null` for default allocation.

## Any of

Type: string
Type: null

##

#### Memory

Memory allocation in bytes or `null` for default allocation.

## Any of

Type: integer
Type: null

##

#### Autostart

Type: boolean

Whether the instance automatically starts when the host boots.

##

#### Environment

Type: object

Environment variables to set inside the instance.

##

Each additional property must conform to the following schema

Type: string

##

#### Aliases

Type: array of object

Array of IP aliases configured for the instance.

No Additional Items

##### Each item of this array must be:

#### VirtInstanceAlias

Type: object
No Additional Properties

##

#### Type

Type: enum (of string)

Type of IP address (INET for IPv4, INET6 for IPv6).

##### Must be one of:

- "INET"
- "INET6"

##

#### Address

Type: string

IP address for the virtual instance.

Must be at least `1` characters long

##

#### Netmask

Network mask in CIDR notation.

## Any of

Type: integer
Type: null

##

#### Image

Type: object

Image information used to create this instance.

No Additional Properties

##

#### Architecture

Hardware architecture of the image (e.g., amd64, arm64).

## Any of

Type: string
Type: null

##

#### Description

Human-readable description of the image.

## Any of

Type: string
Type: null

##

#### Os

Operating system family of the image.

## Any of

Type: string
Type: null

##

#### Release

Version or release name of the operating system.

## Any of

Type: string
Type: null

##

#### Serial

Unique serial identifier for the image.

## Any of

Type: string
Type: null

##

#### Type

Type of image (container, virtual-machine, etc.).

## Any of

Type: string
Type: null

##

#### Variant

Image variant (default, cloud, minimal, etc.).

## Any of

Type: string
Type: null

##

#### Secureboot

Whether the image supports UEFI Secure Boot.

## Any of

Type: boolean
Type: null

##

User namespace ID mapping configuration for privilege isolation.

## Any of

#### UserNsIdmap

Type: object
No Additional Properties

##

User ID mapping configuration for user namespace isolation.

## Any of

#### IdmapUserNsEntry

Type: object
No Additional Properties

##

#### Hostid

Type: integer

Starting host ID for the mapping range.

##

#### Maprange

Type: integer

Number of IDs to map in this range.

##

#### Nsid

Type: integer

Starting namespace ID for the mapping range.

Type: null

##

Group ID mapping configuration for user namespace isolation.

## Any of

#### IdmapUserNsEntry

Type: object
No Additional Properties

##

#### Hostid

Type: integer

Starting host ID for the mapping range.

##

#### Maprange

Type: integer

Number of IDs to map in this range.

##

#### Nsid

Type: integer

Starting namespace ID for the mapping range.

Type: null
Type: null

##

#### Raw

Raw low-level configuration options (advanced use only).

## Any of

Type: object
Type: null

##

#### Vnc Enabled

Type: boolean

Whether VNC remote access is enabled for the instance.

##

#### Vnc Port

TCP port number for VNC connections or `null` if VNC is disabled.

## Any of

Type: integer
Type: null

##

#### Vnc Password

Password for VNC access or `null` if no password is set.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Secure Boot

Whether UEFI Secure Boot is enabled (VMs only) or `null` for containers.

## Any of

Type: boolean
Type: null

##

#### Privileged Mode

Whether the container runs in privileged mode or `null` for VMs.

## Any of

Type: boolean
Type: null

##

#### Root Disk Size

Size of the root disk in GB or `null` for default size.

## Any of

Type: integer
Type: null

##

#### Root Disk Io Bus

Type: enum (of null or string)

I/O bus type for the root disk or `null` for default.

##### Must be one of:

- "NVME"
- "VIRTIO-BLK"
- "VIRTIO-SCSI"
- null

##

#### Storage Pool

Type: string

Storage pool in which the root of the instance is located.

Must be at least `1` characters long

Required roles: VIRT_INSTANCE_WRITE