Instances

Instances allow users to configure Incus-based containers or VMs in TrueNAS.

Linux containers, powered by LXC, offer a lightweight, isolated environment that shares the host system kernel while maintaining its own file system, processes, and network settings. Containers start quickly, use fewer system resources than VMs, and scale efficiently, making them ideal for deploying and managing scalable applications with minimal overhead.

Virtual machines (VMs), powered by QEMU, offer full OS isolation, kernel independence, and can run diverse OS types. VMs emulate hardware, providing greater isolation than containers but requiring more system resources, making them ideal for legacy applications, full-featured desktops, or software with strict OS dependencies.

You must choose a pool before you can deploy an instance. The Instances screen header displays a Pool is not selected status before a pool for instances is selected. See Choosing the Instances Pool below for more information about pool selection.

After setting the pool, Initialized shows on the screen header.

For more information on screens and screen functions, refer to the UI Reference article on Instances Screens.

Use the Configuration dropdown to access the Global Settings, Manage Volumes, and Map User/Group IDs options.

Click Global Settings on the Configuration menu to open the Global Settings screen, showing global options that apply to all instances. Use these options to configure the storage pool for instances and network settings.

You must set the pool before you can add any instances.

Use the use the Pool dropdown to select the pool and click Save.

We recommend users keep the VM and container use case in mind when choosing an instances pool. Select a pool with enough storage space for all the instances you intend to host.

For stability and performance, we recommend using SSD/NVMe storage for the instances pool due to their faster speed and resilience for repeated read/writes.

To select a different pool for instances to use, use the Pool dropdown to select a different pool. Select [Disabled] to deactivate the pool and disable the instances service.

Use the Default Network settings on the Global Settings screen to define how instances connect to the network. These settings apply to all new containers and VMs, unless configured otherwise.

Select Automatic from the Bridge dropdown list to use the default network bridge for communication between instances and the TrueNAS host. To specify an existing bridge, select one from the dropdown list. See Accessing NAS from VMs and Containers for details.
When Bridge is set to Automatic, the IPv4 Network and IPv6 Network settings display.

Enter an IPv4 address and subnet (e.g., 192.168.1.0/24) in IPv4 Network to assign a specific network for instances. Leave this field empty to allow TrueNAS to assign the default address.

Enter an IPv6 address and subnet (e.g., fd42:96dd:aef2:483c::1/64) in IPv6 Network or leave this field empty to allow TrueNAS to assign the default address.

Adjust these settings as needed to match your network environment and ensure proper connectivity for instances.

Click Manage Volumes on the Configuration menu to open the Volumes screen, which lists all the volumes currently configured for the instances service.

Click Create Volume to open the Create New Volume dialog to configure a new instances volume.

Click Import Zvols to open the Import Zvol dialog to import an existing Zvol as an instances volume.

Click Upload ISO to open a file browser to select an .iso file from the client computer and upload it to TrueNAS for use in instances.

Click Create Volume on the Volumes screen to open the Create New Volume dialog.

Enter a name for the volume.

Enter a size for the volume, for example 1 GiB.

Click Create to create the new volume.

Click Import Zvols on the Volumes screen to open the Import Zvol dialog.

Enter the path or browse to select an existing Zvol in Select Zvols.

Select Clone to clone and promote a temporary snapshot of the zvol into a custom storage volume. This option retains the original zvol while creating an identical copy as an instances volume.

Select Move to relocate the existing zvol to the ix-virt dataset as a volume.

Click Upload ISO to open a file browser. Select an .iso file from your client computer to upload it to TrueNAS for use in instances.

Click Configuration > Manage Volumes to access the Volumes screen. Click delete on an volume row to delete that volume. The Delete volume dialog displays.

Select Confirm and then click Continue to delete the image. TrueNAS disables the delete icon for active images to prevent accidental deletion.

Click Map User/Group IDs on the Configuration dropdown list to open the Map User and Group IDs screen, which allows you to manually configure UID and GID mappings inside instances. By default, user and group accounts within an instance are assigned UIDs and GIDs from a special private range starting at 2147000001. This mapping ensures security isolation for containers. However, you can override these mappings to meet specific system requirements.

Select Users or Groups to view mappings for individual user or group accounts, respectively.

Existing mappings are shown in a table containing the user or group name, host ID, and instance ID. Click delete Delete on a row to delete that mapping.

To configure a new mapping, type an account name to search for it or select it from the dropdown list. Select Map to the same UID/GID in the instance to directly map the host ID to the same ID in instances. This means that the selected user or group ID on the host appears as the same ID in instances.

Disable Map to the same UID/GID in the instance to define a different instance ID for the user or group. Enter an ID number to map in instances, for example 1000. This means that the selected user or group ID on the host appears as the configured ID in instances.

Click Set to create the mapping. Changes take effect immediately, though instances can require a restart to reflect the changes.

Incorrect mappings can create permission issues within instances.

Click Create New Instance on the Instances screen to open the Create Instance configuration wizard with the settings to set up a new container or virtual machine.

To create a new container, from the Create Instance screen:

1. Configure the instance configuration settings.

   

   a. Enter a name for the container.

   Instance Name Requirements

   An instance name must meet these criteria:

   • It must be between 1 and 63 characters long.

   • It can only include letters, numbers, and dashes from the ASCII character set.

   • It cannot begin with a number or a dash.

   • It cannot end with a dash.

   b. Select Container as the Virtualization Method.

   c. Click Browse Catalog to open the Select Image screen.

   

   Search or browse to choose a Linux image from linuxcontainers.org. Click Select in the row for your desired image.

2. (Optional) Configure CPU and memory settings.

   

   For containers, enter values for CPU Configuration and Memory Size or leave blank to allow the container access to all host CPU and memory resources. To configure resource allocation:

   a. Enter the number of virtual CPU (vCPU) cores to allocate in CPU Configuration.

   Set to an integer to expose that number of full vCPU cores to the instance.

   Set to a range or comma-separated list to pin vCPUs to specific physical cores. For better cache locality and performance, select cores that share the same cache hierarchy or NUMA node. For example, to assign cores 0,1,2,5,9,10,11, enter 1-2,5,9-11.

   b. Allocate RAM in Memory Size.

   This field accepts human-readable input (Ex. 50 GiB, 500M, 2 TB). If units are not specified, the value defaults to mebibytes (MiB). The minimum value is 32 MiB.

3. (Optional) Configure environment variables to run on boot or execute. Environment settings are only supported for containers and cannot be used with VMs.

   

   a. Click Add to display a set of environment fields.

   b. Enter the name of the environment variable to set (for example, LANG).

   c. Enter the value to assign to the environment variable (for example, en_US.UTF-8).

   Click Add again to configure additional environment variables.

   Click close to delete a configured environment variable.

4. (Optional) Configure disk settings to mount storage volumes for the container. You can create a new dataset or use an existing one.

   

   a. Click Add in the Disks section to display a set of fields to mount a disk.

   b. To create a new dataset, enter a path or browse to select a parent dataset from the dropdown list of datasets on the system. Then click Create Dataset, enter a name for the new dataset in the Create Dataset window, and click Create.

   To use an existing volume, enter a path or browse to select an existing dataset or zvol from the Source dropdown list.

   c. Enter the file system Destination path to mount the disk in the container, for example /media or /var/lib/data.

   d. Click Add again to mount additional storage volumes.

5. (Optional) Configure proxy settings to forward network connections between the host and the container. This routes traffic from a specific address on the host to an address inside the instance, or vice versa, allowing the instance to connect externally through the host.

   

   a. Click Add in the Proxies section to display a set of proxy configuration settings.

   b. Select the protocol option from the Host Protocol dropdown list to set the connection protocol for the TrueNAS host as TCP or UDP.

   c. Enter a port in Host Port to define the TrueNAS port to map to the instance port on the container, for example 3600.

   d. Select the connection protocol for the container in Instance Protocol. Options are TCP or UDP.

   e. Enter the port number within the container in Instance Port, for example 80, to map to the host port.

6. Configure the Network section settings to define how the instance connects to the host and external networks. Options include the default network bridge, an existing bridge interface, or a MACVLAN.

   

   • Use default network settings: Enable to connect the instance to the host using the automatic bridge defined in Global Settings. Disable to show the Bridged NICs (if available) and Macvlan NICs settings.

   

   • To configure non-default network settings, select one or more interface options:

     • Bridged NICs: Use to connect an existing bridge interface to the instance.
     • Macvlan NICs: Use to create a virtual network interface based on an existing interface. A MACVLAN assigns a unique MAC address to the virtual interface so the instance appears as a separate device on the network.

     A MACVLAN NIC on the same physical interface as the TrueNAS host cannot directly communicate with the host. MACVLAN sends traffic directly to the external network without passing through the host network stack. The host does not recognize MACVLAN packets as local, so any traffic between them must be routed through an external switch, use a separate NIC, or use a network bridge.

7. (Optional) Configure USB devices to attach available devices to an instance by selecting one or more in USB Devices. This allows the device to function as if physically connected.

   

8. (Optional) Configure GPU devices in the GPU Devices section to attach available GPU devices, enabling the instance to utilize hardware acceleration for graphics or computation tasks.

   

   Select one or more devices.

   TrueNAS does not have a list of approved GPUs at this time but TrueNAS does support various GPU from Nvidia, Intel, and AMD. As of 24.10, TrueNAS does not automatically install NVIDIA drivers. Instead, users must manually install drivers from the UI. For detailed instructions, see Installing NVIDIA Drivers in TrueNAS Apps.

9. Click Create to deploy the container.

Before creating a VM:

• Obtain an installer .iso or image file for the OS you intend to install, if you are not using a Linux image from the catalog or one previously uploaded to the instances service. You can upload an image for use in instances by using the Manage Volumes option on the Instances screen Configuration menu or you can upload the image from the Instance Configuration settings while creating the VM.

• Create one or more zvols on a storage pool for the virtual disk now or do this from the Volumes screen while configuring the instance.

• Compare the recommended specifications for the guest operating system with your available host system resources. Reference these when allocating resources to the instance.

To create a new virtual machine, from the Create Instance screen:

1. Configure the instance configuration settings.

   

   a. Enter a name for the virtual machine.

   Instance Name Requirements

   An instance name must meet these criteria:

   • It must be between 1 and 63 characters long.

   • It can only include letters, numbers, and dashes from the ASCII character set.

   • It cannot begin with a number or a dash.

   • It cannot end with a dash.

   b. Select VM as the Virtualization Method.

   c. Select one of the available VM Image Options: Use a Linux Image or Upload ISO, import a zvol or use another volume.

   • Select Use a Linux Image to create the VM using a Linux image from linuxcontainers.org.

     a. Click Browse Catalog to open the Select Image screen.

     

     b. Search or browse to choose an available image.

     c. Click Select in the row for your desired image.

   • Select Upload ISO, import a zvol or use another volume to create the VM using an .iso image, import a zvol from a previously installed VM, or use an existing instances volume.

     Click Select Volume to open the Volumes screen.

     

     Use one of the available options to select or create a volume:

     • Using an existing volume:

       Click Select on an existing volume to use that for the new VM. The selected volume cannot be in use by an existing instance.

     • Creating a new volume:

       a. Click Create Volume to open the Create New Volume dialog.

       

       b. Enter a name for the volume.

       c. Enter a size for the volume, for example 1 GiB.

       d. Click Create to create the new volume.

     • Importing a Zvol:

       Use this option to migrate a previously configured VM, such as after updating from TrueNAS 24.10. See Migrating Virtual Machines from the 25.04 release notes for more information.

       a. Click Import Zvols on the Volumes screen to open the Import Zvol dialog.

       

       b. Enter a path in Select Zvols or browse to select an existing Zvol.

       c. Select a method to import the Zvol:

       • Select Clone to clone and promote a temporary snapshot of the zvol into a custom storage volume. This option retains the original zvol while creating an identical copy as an instances volume.

       • Select Move to relocate the existing zvol to the ix-virt dataset as a volume.

     • Uploading an ISO file:

       a. Click Upload ISO to open a file browser and select an .iso file from your client computer.

       b. Locate your desired image file and then click Open to upload the file for use in instances.

2. Configure the CPU and memory settings.

   Compare the recommended specifications for the guest operating system with your available host system resources when allocating CPU and memory resources.

   

   For VMs, CPU and memory configuration is required.

   a. Enter the number of virtual CPU (vCPU) cores to allocate in CPU Configuration.

   Set to an integer to expose that number of full vCPU cores to the instance.

   Set to a range or comma-separated list to pin vCPUs to specific physical cores. For better cache locality and performance, select cores that share the same cache hierarchy or NUMA node. For example, to assign cores 0,1,2,5,9,10,11, enter 1-2,5,9-11.

   b. Allocate RAM in Memory Size.

   This field accepts human-readable input (Ex. 50 GiB, 500M, 2 TB). If units are not specified, the value defaults to mebibytes (MiB). The minimum value is 32 MiB.

3. Configure disks settings to mount storage volumes for the VM. For VMs, you must specify the I/O bus and size of the root disk. You can also mount one or more existing zvol(s) as additional storage, if needed. See Storage volume types from Incus for more information.

   

   a. Choose the root disk I/O bus type that best suits system needs.

   Use NVMe for high-performance storage with faster read/write speeds.

   Use Virtio-BLK for efficient virtualized environments that need direct block device access with lower overhead.

   Use Virtio-SCSI for flexible and scalable storage that supports advanced features like hot-swapping and multiple devices.

   b. Enter a plain integer in Root Disk Size (in GiB) to configure the size of the VM root disk (default 10).

   c. To mount additional storage, click Add to display a set of fields to mount a zvol.

   d. Enter a path or browse to select an existing zvol from the Source dropdown list.

   e. Choose the disk I/O Bus type that best suits system needs. Options are NVMe, Virtio-BLK, or Virtio-SCSI.

   f. Click Add again to mount additional storage volumes.

4. Configure the Network section settings to define how the instance connects to the host and external networks. Options include the default network bridge, an existing bridge interface, or a MACVLAN.

   

   • Use default network settings: Enable to connect the instance to the host using the automatic bridge defined in Global Settings. Disable to show the Bridged NICs (if available) and Macvlan NICs settings.

   

   • To configure non-default network settings, select one or more interface options:

     • Bridged NICs: Use to connect an existing bridge interface to the instance.
     • Macvlan NICs: Use to create a virtual network interface based on an existing interface. A MACVLAN assigns a unique MAC address to the virtual interface so the instance appears as a separate device on the network.

     A MACVLAN NIC on the same physical interface as the TrueNAS host cannot directly communicate with the host. MACVLAN sends traffic directly to the external network without passing through the host network stack. The host does not recognize MACVLAN packets as local, so any traffic between them must be routed through an external switch, use a separate NIC, or use a network bridge.

5. (Optional) Configure USB devices to attach available devices to an instance by selecting one or more in USB Devices. This allows the device to function as if physically connected.

   

6. (Optional) Configure GPU devices in the GPU Devices section to attach available GPU devices, enabling the instance to utilize hardware acceleration for graphics or computation tasks.

   

   Select one or more devices.

   TrueNAS does not have a list of approved GPUs at this time but TrueNAS does support various GPU from Nvidia, Intel, and AMD. As of 24.10, TrueNAS does not automatically install NVIDIA drivers. Instead, users must manually install drivers from the UI. For detailed instructions, see Installing NVIDIA Drivers in TrueNAS Apps.

7. (Optional) Configure PCI passthrough settings to assign physical PCI devices, such as a network card or controller, directly to a VM. This allows the VM to use the device as if physically attached. The selected PCI device(s) cannot be in use by the host or share an IOMMU group with devices the host requires.

   

   a. Click Add PCI Passthrough to open the Add PCI Passthrough Device screen. The Add PCI Passthrough Device screen lists the available physical PCI devices that can be attached to an instance.

   

   b. Use Search Devices or the Type dropdown to filter available devices.

   c. Click Select on a device row to attach that device.

8. (Optional) Configure the VNC section settings to enable VNC access for a VM, configure the VNC port, and set a VNC password for remote access. When VNC access is enabled, remote clients can connect to VM display sessions using a VNC client.

   

   a. Select Enable VNC to allow remote desktop access via a VNC client.

   b. Enter a port number in VNC Port to define the port that the VM VNC server listens for connections on.

   c. Enter a password in VNC Password to authenticate VNC access to the VM.

   A VNC password is not cryptographically secure. You should not rely on it as a single authentication mechanism for your VMs.

9. (Optional) Configure the security settings to control various system security features, including Trusted Platform Module (TPM) and Secure Boot options. These options help to ensure a secure environment by enabling advanced hardware-based security features during system startup and operation.

   

   There are two options:

   • Add Trusted Platform Module (TPM) enables TPM, a hardware-based security feature that protects sensitive data and ensures integrity. This adds a Trusted Platform Module (TPM) device to the VM.

   • Secure Boot enables UEFI Secure Boot. Secure boot ensures that only trusted, signed software is loaded during the system boot process. This might be incompatible with some images, refer to the guest OS documentation for compatibility information.

10. Click Create to deploy the VM.

Some guest operating systems, such as Windows, require user input during boot to start the installation. If the VM does not boot into the installer automatically, connect using a VNC client and press a key within the first 10 seconds after startup.

Created instances appear in a table on the Instances screen. The table lists each configured instance, displaying its name, type, current status, and options to restart or stop it. Stopped instances show the option to start the instance.

Select the checkbox to the left of Name (select all) or select one or more instance rows to access the Bulk Actions dropdown.

Enter the name of an instance in the Search field above the Instances table to locate a configured instance.

Click restart_alt to restart or stop_circle to stop a running instance. Click play_circle to start a stopped instance.

Select an instance row in the table to populate the Details for Instance widgets with information and management options for the selected instance.

Apply actions to one or more selected instances on your system using Bulk Actions.

Use the dropdown to select Start All Selected, Stop All Selected, or Restart All Selected.

After selecting the instance row in the table to populate the Details for Instance widgets, locate the General Info widget.

Click Edit to open the Edit Instance: Instance screen. The Edit Instance: Instance screen settings are a subset of those found on the Create Instance screen. It includes the general Instance Configuration and CPU and Memory settings for all instances. Additionally, containers include Environment settings and VMs include VNC and Security settings.

Select Autostart to automatically start the instance when the system boots.

For containers, CPU Configuration and Memory Size can be configured or left blank to allow the container access to all host CPU and memory resources. For VMs, CPU and memory configuration is required.

To edit resource allocation:

When VNC access is enabled, remote clients can connect to VM display sessions using a VNC client. These settings are only available for VMs and cannot be used with containers.

Stop the instance before editing VNC settings.

These settings are only available for containers and cannot be used with VMs.

These settings are only available for VMs and cannot be used with containers.

After selecting the instance row in the table to populate the Details for Instance widgets, locate the General Info widget.

Click Delete to open the Delete dialog.

Select Confirm to activate the Continue button. Click Continue to delete the instance.

Use the Devices widget to view all USB, GPU, Trusted Platform Module (TPM), and PCI Passthrough devices attached to the instance.

Click Add to open a list of available USB Devices, GPUs, TPM, and PCI Passthrough devices to attach. Select a device to attach it to an instance.

To attach a PCI passthrough device, click Add Device under PCI Passthrough on the device list to open the Add PCI Passthrough Device. PCI passthrough assigns a physical PCI device, such as a network card or controller, directly to a VM, allowing it to function as if physically attached. The Add PCI Passthrough Device screen lists the available physical PCI devices that can be attached to an instance.

Use Search Devices or the Type dropdown to filter available devices. The selected PCI device(s) must not be in use by the host or share an IOMMU group with any device the host requires.

Click Select to attach the selected device.

Use the Disks widget to view the storage devices attached to the instance, along with their associated paths.

Click Add to open the Add Disk screen for adding new disks to the instance.

Click the the more_vert icon to the right of an existing disk to open the actions menu. Select to either Edit or Delete the disk mount.

For VMs, use the Disks widget to manage the root disk size and I/O Bus. The root disk stores the OS and serves as the boot disk for the VM. Click Change to open the Change Root Disk Setup dialog.

Click Add to open the Add Disk screen for adding new disks to the instance.

Click the the more_vert icon to the right of an existing disk to open the actions menu. Select Edit to edit the disk mount.

For VMs, click Select Volume to open the Volumes screen to create or select a volume to attach. Enter a Boot Priority value to set the order in which to boot disks. By default, the root disk is set to 1, which is the highest priority. Select the I/O Bus for the disk. Options are NVMe, Virtio-BLK, and Virtio-SCSI.

For containers, enter or browse to select the host Source path for the disk. For a new dataset, enter or browse to select the parent path. Enter the Destination path to mount the disk in the instance.

Click Save to apply changes.

Click the the more_vert icon to the right of an existing disk to open the actions menu. Select Delete to delete the disk mount.

The Delete Item dialog asks for confirmation to delete the selected disk mount.

Click Confirm to activate the Continue button. Click Continue to start the delete operation.

Click Change to the right of the root disk to open the Change Root Disk Setup dialog.

Enter a new root disk size in GiB, such as 20.

Select the Root Disk I/O Bus. Options are NVMe, Virtio-BLK, and Virtio-SCSI.

Click Save to apply changes.

Use the NIC Widget to view the network interfaces (NICs) attached to the instance, along with their names and types.

ClickAdd to open a menu with available NIC choices. Select a NIC from the dropdown to attach it to the instance.

Click the the more_vert icon to the right of an existing NIC to open the actions menu. Select Delete to delete the NIC mount.

Click Confirm to activate the Continue button. Click Continue to start the delete operation.

Use the Proxies widget to view the network proxy settings configured for the instance. It allows you to manage these settings, including adding, editing, or removing proxies. Proxies are available for containers only and cannot be used with VMs.

Click Add to open the Add Proxy screen to configure a new proxy for the instance.

For existing proxies, click more_vert to open the actions menu with options to Edit or Delete the proxy.

Use the Add Proxy or Edit Proxy screen to configure or modify a proxy setting attached to an instance.

Select a Host Protocol to set the connection protocol for the TrueNAS host. Options are TCP or UDP.

Enter a port number in Host Port to map to the instance port on the container, for example 3600.

Select an Instance Protocol to set the connection protocol for the container. Options are TCP or UDP.

Enter a port number for the container in Instance Port, for example 80.

Click Save to apply changes.

For existing proxies, click more_vert to open the actions menu. Select Delete to remove the proxy configuration.

Click Confirm to activate the Continue button. Click Continue to start the delete operation.

After selecting the instance row in the table to populate the Details for Instance widgets, locate the Tools widget. You can open a shell, console, or VNC session directly from this widget.

Click Shell to open an Instance Shell session for command-line interaction with the instance.

For VMs, click Serial Console to open an Instance Console session to access the system console for the instance.

For VMs, click VNC to open a VNC connection using your preferred client. It uses a VNC URL scheme (for example, vnc://hostname.domain.com:5930) to launch the session directly in the application. If your environment does not support VNC URLs, you can manually connect using a VNC client by entering the host name or IP address followed by the port number without vnc:// (for example, hostname.domain.com:5930 or IP:5930).