---
title: Non-Persistent Virtual Device Infrastructure (NP-VDI)
slug: neurons/help/en_us/non-persistent-virtual-device-infrastructure-np-vdi
createdAt: 2026-11-05T08:02:07.937Z
---

NP-VDI enables your IT team to rapidly provision virtual desktops alongside physical devices, all from a single unified platform. The built-in automated management saves time, reduces manual overhead, and gains comprehensive endpoint control in cloud environments.

## Feature Workflow

### Agent Deployment on Base Image:

- The agent is installed (not registered) on a clean VM.
- The agent is then manually registered as a "Base Image" using the provided command-line tooling.

### Sealing the base image:

- Once the base image agent has registered and the configuration is validated, the VM is "sealed" via the command line.

### Spawning Instances:

- New NP-VDI instances can be spun up from the base image, typically generating a new MAC address for each session.
- Ivanti Neurons detects and tracks these as unique, short-term endpoints managed under the base image.

### Policy Management:

- Policy changes can be made at the base image level. All spawned instances inherit the latest applied policy upon the next check-in.

## Step 1: Prepare the Base Image

To prepare the base image, follow these steps:

1. Navigate to **Agent** > **Agent Deployment** > **Manual installation**.
2. On the Manual installation tab, choose an agent policy and enrollment key.
3. Select **Windows**. Then, choose an **Installation Mode** and click **Download**.
   The agent installer will be downloaded.

   :::hint{type="info"}
   This action downloads two files. Save the installer with file name "**IvantiCloudAgent.exe.options**". This file will be used for installation.
   :::
4. Install the downloaded NP-VDI agent.
   To install the agent:
   - Rename the associated **IvantiCloudAgent.exe.options** file before installation.
     This ensures that the agent executable avoids using the **.options** file that contains tenant registration details.
   - Run the installer. When the Activation key or Cookie option appears and click **Cancel**.
     This installs the agent on the endpoint without registering it to the tenant.
5. Register the agent as a base image. To register as a base image, run the following command, as an administrator, from the agent install location:

   ```bash
   STAgentCtl.exe register --asBaseImage <Base Image Name> --instanceIdType MacAddress --enrollmentkey "%enrollmentkey%" --baseurl https://agentreg.ivanticloud.com
   ```

   In the above command:

   - **\<Base Image Name>** is the name of the base image device.
   - **%enrollmentkey%** is a combination of *tenantid\_activationkey*.
   - **instanceIdType** can be "MacAddress", "HostName" or "Custom". This is used as the unique flag to identify the instance.
     If "Custom" is used, a tagList option containing comma-separated list of custom tags can be specified to identify that agent. For more information about custom tags, see the [Custom Tag List](docId:2bvRr-HJ49GGB07gavFKA) and [Update Tags](docId:2bvRr-HJ49GGB07gavFKA) section.

:::Paragraph{indent="2"}
Both the **tenantid** and **activationkey** can be found in the associated **.options** file, downloaded with the agent as shown in the example below:
:::

:::CodeblockTabs{indent="2"}
```bash
tenantid = 11111111-1111-1111-1111-4gc02d5b0f0d
activationkey = 9aI7SOQNybweiM2QKI7kcqIG8ufUFU21AvZwJwAEx6C-SAO5UGK62YkEgm89kvC2m-xwLesZA4t1_TBtEjIQMVaBU0KsVe-V60ZLBwWu83YREcUp3diAFvHjBvLtkxT3
cloudhost=https:agentreg.ivanticlouddev.com
```
:::

:::Paragraph{indent="2"}
The enrollment key for the above code is:
**%enrollmentkey%** = 11111111-1111-1111-1111-4gc02d5b0f0d\_9aI7SOQNybweiM2QKI7kcqIG8ufUFU21AvZwJwAEx6C-SAO5UGK62YkEgm89kvC2m-xwLesZA4t1\_TBtEjIQMVaBU0KsVe-V60ZLBwWu83YREcUp3diAFvHjBvLtkxT3
The command line to register a device with the example tenant for a base image named "**Win11**" will be as follows:
:::

:::CodeblockTabs{indent="2"}
```bash
STAgentCtl.exe register --asBaseImage Win11 --instanceIdType MacAddress --enrollmentkey "11111111-1111-1111-1111-4gc02d5b0f0d_9aI7SOQNybweiM2QKI7kcqIG8ufUFU21AvZwJwAEx6C-SAO5UGK62YkEgm89kvC2m-xwLesZA4t1_TBtEjIQMVaBU0KsVe-V60ZLBwWu83YREcUp3diAFvHjBvLtkxT3" --baseurl https://agentreg.ivanticloud.com
```
:::

6. To update the base image:
   - Download the PowerShell script from Ivanti community portal: [Ivanti-Neurons -Non-Persistent-VDI - Agent Script](https://forums.ivanti.com/s/article/Ivanti-Neurons---Non-Persistent-VDI-Support---Updating-Non-Persistent-Agents-Script).
   - Before running the PowerShell script, check that the admin has the relevant permissions to run this on the base image, as the execution policy on the endpoint may block this:
     - To check, use "**Get-ExecutionPolicy**" command.
     - To change, use "**Set-ExecutionPolicy RemoteSigned**" command.
   - If the script runs without any parameters, the script will attempt the following:
     - Unseal the agent.
     - Run updates for both agents and engines.
     - Seal the agent again.
   - If the agent is already unsealed, and this should remain unsealed after the update. Pass the "**DoNotSeal**" parameter to perform all the same steps, except sealing the image.
   - The default timeout for updates is 300 seconds. You can change the time by passing the "**-TimeoutSec**" argument.

:::Paragraph{indent="2"}
For additional reference, copy of the script can be accessed under [Appendix](docId:2bvRr-HJ49GGB07gavFKA) section.
:::

7. To prepare the base image:
   - Run "**STAgentCtl.exe prepareImage**" command to make a sealed, non-persistent base image ready for NP-VDI.
     This command is mandatory and stops all services and deletes any data related to actual Agent ID of the base image. When the non-persistent instance boots up, the services are restarted.

     :::hint{type="info"}
     The Agent ID will change with every non-persistent instance spun up from the base image.
     :::
   - Use the following commands to manually seal the base image (outside of the upgrade script):
     - To manually seal the base image, enter "**STAgentCtl.exe seal**".

       :::hint{type="info"}
       Use the "**unseal**" command to unseal the image. This remains active until a system restart or the "**Seal**" command is used.
       :::
8. (Optional) Prepare the image for use with "**sysprep**".
   If the non-persistent desktop preparation includes a sysprep stage, it will remove the private key of the agent certificate from the certificate store. To address this issue, follow these steps:

   :::hint{type="info"}
   The admin must supply their own certificate export password; otherwise, this process will fail.
   :::

   1. Locate the certificate serial number using the **certutil -store "Ivanti Cloud Agent Agent"**
   2. The certificate with the subject OU "ST Agent" (e.g. "Subject: OU=ST Agent, CN=011472EFB12BABF06122F2903BBE12AC4E32EBFE5082") should be exported, using the corresponding serial number from that entry.
      After running the command "**stagentctl prepareImage**" at Step 7, you can export the agent certificate using the following command:

      ```bash
      certutil -exportPFX -privatekey -p "%pfxpass%" "Ivanti Cloud Agent Agent" %serialnumber% "%ProgramFiles%\Ivanti\Ivanti Cloud Agent\agent.pfx" NoChain,NoRoot
      ```

      In the above command:

      - **%pfxpass%** is a password supplied by the admin.
      - **%serialnumber%** is the located serial number of the agent certificate.
   3. Download the **SetupComplete.cmd** script available from Ivanti's community website here: [Restore private key from exported .pfx file script](https://forums.ivanti.com/s/article/Ivanti-Neurons---Non-Persistent-VDI-Support---Restore-private-key-from-exported-pfx-file-script).
   4. Edit the **SetupComplete.cmd** script and update the password to match the password used to export the certificate used in [Step 2](docId:2bvRr-HJ49GGB07gavFKA).
   5. Store the script at **%WINDIR%\Setup\Scripts\SetupComplete.cmd** on the gold image.
      The script will automatically run once the Windows setup has been completed (which happens the first time the device is booted after sysprep).

      :::hint{type="info"}
      This will restore the private key from the exported .pfx file, then delete both the .pfx file and the script itself, so that the secret won’t leak into the non-persistent instances.
      :::

## Step 2: Create and Test NP-VDI Instances

To spin a new instance from the base image, follow these steps:

1. Ensure a new MAC address is assigned to each new instance (to ensure the instanceIdType MacAddress option will work).
   Alternatively, ensure a different hostname or tag is utilized.
2. Start the virtual machine instance and confirm the instance appears in the Neurons UI as a unique NP-VDI endpoint. Go to **Agents** > **Agent** Management section of Ivanti Neurons interface to do this.
   A new **VDI Type** column is available which indicates whether the device is a Base Image, Non-Persistent, or Persistent device.
3. Each agent endpoint is now linked from the Agent Management page to the Devices page. Click on the Agent Endpoint name to launch a new window showing the device in the Devices view.
4. Click the **Linked instances** option to show all the instances spun up from this base image.
   The Non-Persistent Instances will be tagged as Non-persistent in the Devices view.

## Step 3: Reassigning Policy with NP-VDI

To reassign a policy to the base image directly from the Ivanti Neurons interface, follow these steps:

1. Navigate to **Agents** > **Agent Policies**.
2. Select the base image and choose **Reassign Policy** from the **Actions** menu.
3. Choose the policy to reassign and click **Save**.
   This reassigns the policy. After the policy is reassigned to the base image, all the non-persistent VDI instances will inherit the policy the next time they check-in (which by default is every 200 minutes).
4. Validate that new instances inherit the updated policy after check in, either using the Ivanti Neurons Agents or Agent Management interface or from the non-persistent image itself, using the command line "**Stagentctl status**".

:::hint{type="info"}
It is not possible to perform reboot actions on a NP-VDI instance. This would reset the device to its initial state, potentially causing the user to lose work they completed during their session.
In addition, Actions available from the Devices view for non-persistent instances do not contain reboot actions.
:::

## Things to Note

### Sealed and Unsealed Agents

A sealed agent will not update itself, attempt to recertify, or allow itself to be uninstalled. Follow the list below for the behavior of a sealed agent:

- Sealed agents can get a new policy in response to a check-in.
  - Sealed agents will not install or uninstall any engines in response to a policy change.
- Sealed agents will update content, but will not update engines.
- Sealed and unsealed agents will not attempt to recertify.
- Sealed agents will not uninstall themselves.
- Only agents registered as base images can be sealed.
- An agent installed and registered as a base image will be automatically sealed after the agent has registered, completed its initial check-in, and installed all relevant engines.
- A sealed agent will check in immediately when it starts.
- Sealed agents will always augment their agent ID with an instance ID.

### Recertification

The agent recertification process involves the agent updating Ivanti Neurons with its new public key. This communication is authenticated using the agent’s existing key pair. After an agent recertifies, Ivanti Neurons will expect it to communicate with its new certificate.

In the case of NP-VDI instances, the result of an instance recertifying by mistake or mischief is that all instances and the base image will lose their security association to Ivanti Neurons. This would cause a serious disruption to all instances that share the base image. As a result of these risks, the agent will not attempt to recertify any agent that is either an NP-VDI base image or NP-VDI instance.

Instead, Ivanti Neurons will require administrators to re-register the base image to establish a fresh key-pair. As this is recommended to be performed once every 12 months, and we expect NP-VDI base images to be updated more frequently than that, we expect that this requirement is justified to prevent the risks expressed above.

## Additional STAgentCtle.exe Commands

You can use the following additional commands:

- To open the base agent for updates, enter the "**Stagentctl.exe unseal**" command.
- To force the command line to wait until the update has completed before returning control, enter the "**Stagentctl.exe update –wait**" command.

  :::hint{type="info"}
  The "wait" command may encounter problems when the agent is updated, as it requires the agent executables to be running, which leads to the need for a reboot after the update. To avoid this issue, Ivanti offers a [PowerShell script](docId:2bvRr-HJ49GGB07gavFKA) that allows for a synchronous update command to be executed.
  :::
- To close the base agent for updates, enter the "**Stagentclt.exe seal**" command.

## Custom Tag List

A Custom Tag List is a user-defined collection of tags that can be assigned to endpoints in Ivanti Neurons, including NP-VDI instances. Custom tags help classify, organize, and identify devices based on business, operational, or technical requirements.

For example, using the tag "Sales-\[MacAddress]" generates a unique tag for each device by replacing \[MacAddress] with the device's actual MAC address. This functionality is particularly useful for generating unique tags for non-persistent VDI instances.

Use the following syntax to reference device attributes and environment variables:

- To reference the MAC address, use "**\[MacAddress]**"
- To reference the hostname, use "**\[HostName]**"
- To reference an environment variable, use "**\[env:\<name>]**"

Where **\<name>** is the case-sensitive name of the environment variable.

## Update Tags

Tags assigned during base image registration remain static for all associated instances. If you need to update tags, re-register/seal the base image, or use automation to assign tags based on current criteria after VM deployment.

## Appendix

:::ExpandableHeading
## Update-NonPersistentAgent.ps1

```bash
```

\<#

.SYNOPSIS

Updates a non-persistent agent, waiting for the update to complete, then optionally sealing the agent.

.PARAMETER TimeoutSec

Total timeout in seconds.

.PARAMETER UpgradeCode

Upgrade code of the agent being updated.

.PARAMETER DoNotSeal

This parameter specifies not to seal the agent after updating.

\#>

param

(

\[int] $TimeoutSec = 300,

\[guid] $UpgradeCode = "", # Neurons Agent

\[switch] $DoNotSeal

)

function Check-UpdatersComplete

\{

$updaters = Get-Process -Name "STAgentUpdater" -ErrorAction SilentlyContinue

return ($updaters.Count -eq 0)

}

function Wait-UpdatersComplete(\[DateTime] $timeoutDateTime, \[int] $checkIntervalSec)

\{

while ((Get-Date) -lt $timeoutDateTime)

\{

if (Check-UpdatersComplete)

\{

return

}

Start-Sleep -Seconds $checkIntervalSec

}

throw "Timeout waiting for all updaters to complete."

}

function Get-AgentVersionFromManifest(\[string] $manifestPath, \[string] $platformKey)

\{

if (-not (Test-Path $manifestPath))

\{

throw "Could not find manifest at '$manifestPath'."

}

\[xml]$manifestXml = Get-Content $manifestPath

$agentFile = $manifestXml.manifest.files.file | Where-Object \{ $\_.key -eq $platformKey }

if (-not ($agentFile))

\{

throw "Agent entry with key='$platformKey' not found."

}

if (-not ($agentFile.version))

\{

throw "Unable to find agent version in manifest."

}

return \[version]\::Parse($agentFile.version)

}

function Get-CurrentAgentVersion(\[guid] $agentUpgradeCode)

\{

$agentProductCode = Get-ProductCode -UpgradeCode $agentUpgradeCode

$agentObject = Get-WmiObject -Class Win32\_Product | Where-Object \{ \[guid]\::Parse($\_.IdentifyingNumber) -eq $agentProductCode }

if (-not ($agentObject))

\{

throw "Installed agent not found."

}

if (-not ($agentObject.Version))

\{

throw "Installed agent version not found."

}

return \[version]\::Parse($agentObject.Version)

}

function Check-AgentUpToDate(\[string] $manifestPath, \[guid] $agentUpgradeCode, \[string] $platformKey)

\{

$manifestVersion = Get-AgentVersionFromManifest -ManifestPath $manifestPath -PlatformKey $platformKey

$currentVersion = Get-CurrentAgentVersion -AgentUpgradeCode $agentUpgradeCode

return ($currentVersion -ge $manifestVersion)

}

function Wait-AgentUpdated(\[DateTime] $timeoutDateTime, \[int] $checkIntervalSec, \[string] $manifestPath, \[guid] $agentUpgradeCode, \[string] $platformKey)

\{

while ((Get-Date) -lt $timeoutDateTime)

\{

if (Check-AgentUpToDate -ManifestPath $manifestPath -AgentUpgradeCode $agentUpgradeCode -PlatformKey $platformKey)

\{

return

}

Start-Sleep -Seconds $checkIntervalSec

}

throw "Waiting for agent update timed out."

}

function Update-Agent(\[DateTime] $timeoutDateTime, \[string] $manifestPath, \[guid] $agentUpgradeCode, \[string] $agentCtlPath, \[string] $platformKey)

\{

$timeoutSec = \[math]\::Ceiling(($timeoutDateTime - (Get-Date)).TotalSeconds)

if ($timeoutSec -le 0)

\{

throw "Can't run check-in because of small timeout."

}

& $agentCtlPath update --checkin --wait $timeoutSec

if (-not $?)

\{

throw "Check-in operation failed."

}

& $agentCtlPath update --all

if (-not $?)

\{

throw "Update operation failed."

}

Wait-AgentUpdated -TimeoutDateTime $timeoutDateTime -CheckIntervalSec 1 -ManifestPath $manifestPath -AgentUpgradeCode $agentUpgradeCode -PlatformKey $platformKey

Wait-UpdatersComplete -TimeoutDateTime $timeoutDateTime -CheckIntervalSec 1

$timeoutSec = \[math]\::Ceiling(($timeoutDateTime - (Get-Date)).TotalSeconds)

if ($timeoutSec -le 0)

\{

throw "Can't run final update because of small timeout."

}

& $agentCtlPath update --all --wait $timeoutSec

if (-not $?)

\{

throw "Final update operation failed."

}

}

function Get-ProductCode(\[guid] $upgradeCode)

\{

$upgradeCodeStr = $upgradeCode.ToString("B") # Format as&#x20;

$wmiFilter = "Property='UpgradeCode' AND Value='$upgradeCodeStr'"

$productCode = @(Get-WmiObject -Class Win32\_Property -Filter $wmiFilter).ProductCode

if ($productCode.Count -eq 0)

\{

throw "Upgrade code '$upgradeCode' not found."

}

if ($productCode.Count -gt 1)

\{

throw "Multiple products with the same upgrade code '$upgradeCode' were found."

}

return \[guid]\::Parse($productCode)

}

function Get-AgentEnvironment(\[string] $installDirPath)

\{

$configPath = Join-Path $installDirPath "AgentEnvironment.config"

if (-Not (Test-Path $configPath))

\{

throw "Config file not found at $configPath."

}

\[xml]$agentEnvironment = Get-Content $configPath

return $agentEnvironment

}

function Get-InstallLocation(\[guid] $productCode)

\{

$productObject = Get-WmiObject -Class Win32\_Product | Where-Object \{ \[guid]\::Parse($\_.IdentifyingNumber) -eq $productCode }

if ($null -eq $productObject)

\{

throw "The product GUID was not found."

}

return $productObject.InstallLocation

}

$timeoutDateTime = (Get-Date).AddSeconds($TimeoutSec)

Write-Host "Gathering information..."

try

\{

$agentProductCode = Get-ProductCode -UpgradeCode $UpgradeCode

$installDirPath = Get-InstallLocation -ProductCode $agentProductCode

Write-Host " Install directory: $installDirPath"

$agentEnvironment = Get-AgentEnvironment -InstallDirPath $installDirPath

$dataDirPath = $agentEnvironment.agentEnvironment.agentDataDirectory

Write-Host " Data directory: $dataDirPath"

$regPath = Join-Path "HKLM:" $agentEnvironment.agentEnvironment.registryPath

Write-Host " Registry key: $regPath"

$platformKey = Get-ItemProperty -Path $regPath -Name "PlatformManifestKey" -ErrorAction Stop | Select-Object -ExpandProperty "PlatformManifestKey" -ErrorAction Stop

Write-Host " Platform key: $platformKey"

$agentCtlPath = Join-Path $installDirPath "STAgentCtl.exe"

$manifestPath = Join-Path $dataDirPath "manifest.xml"

}

catch

\{

Write-Error "ERROR: $\_"

exit -1

}

if ((Get-Date) -gt $timeoutDateTime)

\{

Write-Error "ERROR: The timeout expired before the agent update could begin."

exit -1

}

Write-Host "Unsealing the agent..."

& $agentCtlPath unseal

if (-not $?)

\{

Write-Error "ERROR: can't perform unseal operation."

exit -1

}

Write-Host "Updating the agent..."

$result = -1

try

\{

Update-Agent -TimeoutDateTime $timeoutDateTime -ManifestPath $manifestPath -AgentUpgradeCode $UpgradeCode -AgentCtlPath $agentCtlPath -PlatformKey $platformKey

$result = 0

}

catch

\{

Write-Error "ERROR: $\_"

}

if ($DoNotSeal)

\{

if ($result -eq 0)

\{

Write-Host "The agent has been successfully updated."

}

else

\{

Write-Error "ERROR: agent update failed."

}

exit $result

}

Write-Host "Sealing the agent..."

& $agentCtlPath seal

if (-not $?)

\{

Write-Error "ERROR: can't seal the agent!"

exit -1

}

if ($result -eq 0)

\{

Write-Host "The agent has been successfully updated and sealed."

}

exit $result
:::

:::ExpandableHeading
## SetupComplete.cmd

(@ECHO OFF

set pw=supersecret

set logfile=C:\ProgramData\Ivanti\Ivanti Cloud Agent\Logs\agentkeyrestore.log

set certFile=C:\Program Files\Ivanti\Ivanti Cloud Agent\agent.pfx

set scriptPath=%0%

ECHO %date% %time% Agent key restore started >> "%logfile%"

IF EXIST "%certFile%" (

certutil -f -p "%pw%" -privatekey -importPFX "Ivanti Cloud Agent Agent" "%certFile%" NoCert,NoExport >> "%logfile%" 2>&1

IF %ERRORLEVEL% NEQ 0 (

ECHO Failed to import agent key >> "%logfile%"

)

ECHO Removing agent key file >> "%logfile%"

del "%certFile%" >> "%logfile%" 2>&1

IF %ERRORLEVEL% NEQ 0 (

ECHO Failed to delete agent key file >> "%logfile%"

)

ECHO %date% %time% Agent key restore complete >> "%logfile%"

) ELSE (

ECHO %date% %time% Agent key restore failed: no agent key file found >> "%logfile%"

)

ECHO Removing script >> "%logfile%"

del "%scriptPath%" >> "%logfile%" 2>&1

"REM no further commands can be executed from this point because script file has been deleted"
:::
