TrueNAS Nightly Development Documentation
This content follows experimental nightly development software. Pre-release software is intended for testing purposes only.
Use the Product and Version selectors above to view content specific to a stable software release.
Instances
24 minute read.
Virtual Machines and Containers in TrueNAS 25.04 and LaterTrueNAS 25.04 replaces the previous KVM hypervisor (TrueNAS 24.10 and earlier) with Incus for virtual machine (VM) deployment. It also introduces support for Linux system containers (LXC), enabling lightweight isolation similar to jails in TrueNAS CORE.
With this change, the Instances (formerly Virtualization) screens in the TrueNAS UI are fully redesigned. We are actively updating Tutorials and UI Reference articles to reflect these changes. Please use the Docs Hub Feedback button (located to the right of any article) to report documentation issues or request improvements to the Instances documentation.
Instances (Incus-powered containers and virtual machines) are an experimental feature intended for community testing only. Functionality could change significantly between releases, and instances might not upgrade reliably. Use this feature for testing purposes only—do not rely on it for production workloads. Long-term stability is planned for future TrueNAS Community Edition releases.
Make all configuration changes using the TrueNAS UI. Operations using the command line are not supported and might not persist on upgrade.
For assistance or to discuss this feature with other TrueNAS users, visit our community forums.
To report bugs, submit an issue on TrueNAS Jira.
The Instances screen allows users to add, edit, or manage virtual machines (VMs) and Linux containers.
The screen header displays a Pool is not selected status before a pool for instances is selected. See Global Settings for more information.
After setting the pool, Initialized shows on the screen header.
The Instances screen displays No Instances before you create the first instance.
The Configuration dropdown menu includes Global Settings, Manage Volumes, and Map User/Group IDs options.
Create New Instance at the top right of the screen opens the Create Instance wizard.
Configuration on the Instances screen header displays service-level settings that apply to all instances.
- Global Settings opens the Global Settings screen.
- Manage Volumes opens the Volumes screen.
- Map User/Group IDs opens the Map User And Group IDs screen.
Global Settings opens the Global Settings screen showing global options that apply to all instances, including selecting the storage pool for instances and network settings.
The Pool dropdown list shows a list of available pools on the system. [Disabled] deactivates the pool and disables the instances service.
The screen header displays a Pool is not selected status before a pool for instances is selected.
Default Network settings configure global networking defaults for the instances service.
| Setting | Description |
|---|---|
| Bridge | Specifies the network bridge. Automatic uses the default network bridge for communication between instances and the TrueNAS host. The dropdown list option shows existing bridges. See Accessing NAS from VMs and Containers for more information. |
| IPv4 Network | Specifies the IPv4 address for the bridge specified when Bridge is set to Automatic. Enter the IPv4 address and subnet (e.g., 192.168.1.0/24) for the instances to use or leave empty to allow TrueNAS to use the default address. |
| IPv6 Network | Specifies the IPv6 address for the bridge specified when Bridge is set to Automatic. Enter the IPv6 address and subnet (e.g., fd42:96dd:aef2:483c::1/64) for the instances to use or leave empty to allow TrueNAS to use the default address. |
The Volumes screen lists all volumes currently configured for the instances service.
Create Volume opens the Create New Volume dialog to configure a new instances volume.
Import Zvols opens the Import Zvol dialog to import an existing Zvol as an instances volume.
Upload ISO opens a file browser to select an
Create Volume on the Volumes screen opens the Create New Volume dialog.
| Setting | Description |
|---|---|
| Name | Name of the volume. Enter a name for the volume. |
| Size | Size of the volume. Enter a size for the volume, for example 1 GiB. |
Create creates the new volume.
Import Zvols on the Volumes screen opens the Import Zvol dialog.
| Setting | Description |
|---|---|
| Select Zvols | Specifies the Zvol to import. Enter or browse to select an existing Zvol. |
| Clone | Clones and promotes 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. |
| Move | Relocates the existing zvol to the ix-virt dataset as a volume. |
delete Delete on an image row deletes that image. A Delete volume dialog displays.
Confirm and then Continue deletes the image. Delete is disabled for active images.
The Map User and Group IDs screen allows users to manually configure UID and GID mappings inside instances.
Existing mappings are shown in a table containing the group or user name, host ID, and instance ID. delete Delete on a row deletes that mapping.
The Users or Groups tabs display mappings for individual user or group accounts, respectively.
Existing mappings are shown in a table containing the group or user name, host ID, and instance ID. delete Delete on a row deletes that mapping.
Set creates the mapping. Changes take effect immediately, but instances might require a restart to reflect the changes.
The Create Instance configuration wizard displays all settings to set up a new container or virtual machine.
The Instance Configuration settings specify the instance name, virtualization method or type, and operating system image.
Instance Configuration Settings - VM
| Setting | Description |
|---|---|
| Name | Required. Enter an alphanumeric name for the instance. |
| Virtualization Method | Required. Select VM to create a fully isolated virtual machine using any operating system. |
| VM Image Options | (Shows when Virtualization Method is set to VM) |
| Use a Linux image | Select to choose a Linux image from linuxcontainers.org. Browse Catalog opens the Select Image screen with available image choices. Search or browse to locate your desired image and click Select. |
| Upload ISO, import a zvol or use another volume | Sets the method to use to for the storage option. Select to create the VM using an |
The CPU & Memory settings specify the number of virtual CPU cores to allocate to the virtual machine and memory size.
The Environment settings configure optional environment variables to run on boot or execute. These settings are only available for containers and cannot be used with VMs.
Add displays a set of environment fields.
The Disks settings allow mounting storage volumes to an instance. Container options include creating a new dataset or using an existing one. VMs use the Volumes screen to select or create a new volume. VMs must specify the I/O bus and size of the root disk.
Add displays a set of fields to create or mount a disk.
The Proxies settings allow you to forward network connections between the host and the instance. 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. These settings are only available for containers and cannot be used with VMs.
Add displays a set of proxy configuration settings.
The Network settings configure how the instance connects to the host and external networks. Options include the default network bridge, an existing bridge interface, or a MACVLAN.
See Accessing NAS from VMs and Containers for more information.
Network Settings
| Setting | Description |
|---|---|
| Use default network settings | Select to use default network settings to connect the instance to the host using the automatic bridge defined in Global Settings. Selected by default. Disable to display the Bridged NICs (if available) and Macvlan NICs settings. |
| Bridged NICs | Select an existing bridge on the TrueNAS host to connect to the instance. Displays when one or more existing bridge interface(s) is available. |
| Macvlan NICs | Select an existing interface to create a virtual network interface based on it, assigning a unique MAC address 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.
USB Devices displays a list of available devices to attach to an instance, allowing the device to function as if physically connected.
GPU Devices displays available GPU devices to attach to an instance, enabling it to utilize hardware acceleration for graphics or computation tasks.
PCI Passthrough settings enable assigning a physical PCI device, such as a network card or controller, directly to a VM, allowing it to use the device as if physically attached. These settings are only available for VMs and cannot be used with containers.
The selected PCI device(s) cannot be in use by the host or share an IOMMU group with devices the host requires.
Add PCI Passthrough opens the Add PCI Passthrough Device screen.
The VNC settings allow you to enable VNC access for a VM, configure the VNC port, and set a VNC password for remote access. These settings are only available for VMs and cannot be used with containers.
The Security settings 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. These settings are only available for VMs and cannot be used with containers.
The Instances table lists each configured instance, displaying its name, type, current state, and options to restart or stop it. Stopped instances show the option to start the instance.
The Details for Instance widgets show information and management options for the selected instance.
restart_alt restarts or stop_circle stops a running instance. play_circle starts a stopped instance.
Search above the Instances table allows entering the name of an instance to locate a configured instance.
The checkbox on each instance row shows the Bulk Actions dropdown.
The Bulk Actions dropdown list allows you to apply actions to one or more instances on your system. Options are Start All Selected, Stop All Selected, and Restart All Selected.
The Details for Instance widgets display information and configuration options for the selected instance.
The General Info widget displays the instance status, autostart setting, base image, CPU, memory, and secure boot configuration. It includes the Edit and Delete buttons for the instance.
Delete opens the Delete dialog.
Edit opens an Edit Instance: Instance configuration screen populated with editable settings also found on the install wizard screen for the instance.
The Delete dialog asks for confirmation to delete the selected instance.
Confirm activates the Continue button. Continue starts the delete operation.
The Devices widget displays all USB, GPU, Trusted Platform Module (TPM), and PCI Passthrough devices attached to the instance.
Add opens a list of available USB Devices, GPUs, TPM, and PCI Passthrough devices.
Add Device under PCI Passthrough opens the Add PCI Passthrough Device screen.
The Disks widget shows the storage devices attached to the instance, along with their associated paths. It allows you to manage the disks, including adding new ones or modifying existing ones.
Add opens the Add Disk screen for adding new disks to the instance.
For existing disks, the actions include options to Edit or Delete the disk mount.
For VMs, the widget displays the current root disk size. The root disk stores the OS and serves as the boot disk for the VM. Change opens the Change Root Disk Setup dialog.
The Add/Edit Disk screen allows you to configure a new disk or modify an existing one attached to an instance.
Add/Edit Disk Settings - Container
| Setting | Description |
|---|---|
| Source | Enter or browse to select the host source path for the disk. For a new dataset, enter or browse to select the parent path. |
| Destination | Enter the destination path to mount the disk in the instance. |
Save applies changes.
The Delete Item dialog asks for confirmation to delete the selected disk mount.
Confirm activates the Continue button. Continue starts the delete operation.
The Change Root Disk Setup dialog allows you to configure the size of the disk a VM stores its OS on and boots from and change the root disk I/O bus.
| Setting | Description |
|---|---|
| Root Disk Size (in GiB) | Increases the size of the VM root disk. Enter a new root disk size in GiB, such as 20. |
| Root Disk I/O Bus | Sets the communication pathway type for the root disk. Options are NVMe, Virtio-BLK, and Virtio-SCSI. |
Save applies changes.
The NIC Widget displays the network interfaces (NICs) attached to the instance, along with their names and types. It allows you to add new NICs and manage existing ones.
Add opens a menu with available NIC choices, allowing you to select and attach a new NIC to the instance.
For existing NICs, the actions menu allows you to delete the NIC.
The Delete Item dialog asks for confirmation to delete the selected NIC.
Confirm activates the Continue button. Continue starts the delete operation.
The Proxies widget displays the network proxy settings configured for the instance. It allows you to manage these settings, including adding, editing, or removing proxies. These settings are only available for containers and cannot be used with VMs.
Add opens the Add Proxy screen to configure a new proxy for the instance.
For existing proxies, the actions menu includes options to Edit or Delete the proxy.
The Add/Edit Proxy screen allows you to configure or modify a proxy setting attached to an instance.
| Setting | Description |
|---|---|
| Host Protocol | Sets the connection protocol for the TrueNAS host. Options are TCP or UDP. |
| Host Port | Sets TrueNAS host port to map to the instance port on the container, for example 3600. |
| Instance Protocol | Sets the connection protocol for the container. Select from the options TCP or UDP. |
| Instance Port | Sets the port number within the container. Enter a port number to use, for example 80. |
Save applies changes.
The Delete Item dialog asks for confirmation to delete the selected proxy configuration.
Confirm activates the Continue button. Continue starts the delete operation.
The Idmap widget shows the user ID (UID) and group ID (GID) mappings used by the instance to translate IDs between the host and the container or VM. It provides details such as the Host ID, Maprange, and NS ID for both UIDs and GIDs. These settings are only available for containers and cannot be used with VMs.
- Host ID shows the starting ID used by the host for mapping to the instance IDs.
- Maprange indicates the range of IDs that the host allocates for the instance.
- NS ID represents the namespace ID used for the mapping.
For example, if the Host ID is 2147000001 and the Maprange is 458752, the container UID 0 (root) is mapped to the host UID 2147000001.
This ensures proper isolation and user/group identity management between the host and the instance.
The Tools widget provides quick access to various tools and utilities for managing your instance. You can open a shell, console, or VNC session directly from this widget.
Shell opens an Instance Shell session for command-line interaction with the instance.
Serial Console (VM only) opens an Instance Console session to access the system console for the instance.
VNC (VM only) opens 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).
The Metrics widget displays real-time graphs that monitor instance performance, including CPU usage, memory usage, and disk I/O pressure.
CPU (%) shows the percentage of CPU usage over time.
Memory (MiB) displays the memory usage in MiB over time.
Disk I/O Full Pressure (%) tracks the disk input/output pressure as a percentage over time.
The Edit Instance: Instance screen settings are a subset of those found on the Create Instance Wizard screens. It includes the general Instance Configuration and CPU and Memory settings for all instances. Additionally, containers include Environment settings. VMs include VNC and Security settings. To edit device, disk, network, or proxy settings, use the Instances Widgets on the Instances screen.
The Instance Configuration settings on the Edit screen allow you to modify basic parameters for the instance, such as startup behavior.
Autostart automatically starts the instance when the system boots.
The CPU & Memory settings on the Edit screen are the same as those in the Create Instance wizard.
The VNC settings on the Edit screen are the same as those in the Create Instance wizard. These settings are only available for VMs and cannot be used with containers.
The Environment settings on the Edit screen are the same as those in the Create Instance wizard. These settings are only available for containers and cannot be used with VMs.
Add displays a set of environment fields.
The Security settings on the Edit screen allow you to enable Secure Boot for the instance, ensuring that only trusted, signed software runs during the startup process. These settings are only available for VMs and cannot be used with containers.
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.
Select attaches the selected device.