> For the complete documentation index, see [llms.txt](https://docs.stepsecurity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stepsecurity.io/developer-machines/installation/script/azure-virtual-desktop-avd.md).

# Azure Virtual Desktop (AVD)

Use this guide when session hosts are built from a master image and provisioned by a host-creation script, such as Nerdio Manager, rather than through an MDM.

Dev Machine Guard is installed on each Azure Virtual Desktop (AVD) session host when the host is created, so every new host has it before its first user signs in.

The master image carries only the installer, configuration and provisioning files. Dev Machine Guard is never installed on the master itself.

**Deployment sequence**

Master image with staged files → image capture → new host and domain join → Dev Machine Guard setup → readiness check → user access

{% hint style="info" %}
The examples below use Nerdio Manager to capture images and run host actions. Any image and host-provisioning tool works if it can run a script as Local SYSTEM on each new host and keep the host out of the host pool until the script succeeds.
{% endhint %}

### Requirements <a href="#user-content-requirements" id="user-content-requirements"></a>

* x64 Windows Enterprise multi-session session hosts.
* The host action runs as **Local SYSTEM** in 64-bit Windows PowerShell 5.1.
* Windows OpenSSH Client is installed and provides `%SystemRoot%\System32\OpenSSH\ssh-keygen.exe` with `-Y verify` support.
* Hosts can reach your tenant's StepSecurity API and the configured update endpoints.
* Dev Machine Guard **1.19.0 or later**. The provisioning scripts, MSI and signature are public on GitHub. Your tenant configuration comes from the StepSecurity console (see [Step 1](#user-content-step-1-prepare-the-deployment-bundle)).

### Step 1: Prepare the deployment bundle <a href="#user-content-step-1-prepare-the-deployment-bundle" id="user-content-step-1-prepare-the-deployment-bundle"></a>

Download all files from the same release. The scripts, MSI and signature must match. Version 1.19.0 or later is required.

1. **Provisioning scripts:** open [dev-machine-guard › scripts/windows (v1.19.0)](https://github.com/step-security/dev-machine-guard/tree/v1.19.0/scripts/windows). Open each of the five `.ps1` and `.psm1` files listed below and select **Download raw file**. Save all five in `C:\StepSecuritySetup` and keep their file names.
2. **Installer:** download the [x64 MSI](https://github.com/step-security/dev-machine-guard/releases/download/v1.19.0/stepsecurity-dev-machine-guard-1.19.0-x64.msi) and its [checksum signature](https://github.com/step-security/dev-machine-guard/releases/download/v1.19.0/stepsecurity-dev-machine-guard-1.19.0-x64.msi.sha256.sig). Save them in the same folder as `agent.msi` and `agent.msi.sha256.sig`.
3. **Tenant configuration:** in the StepSecurity console, go to **Installation > Script > Windows > MSI/SCCM > Generate script**. Save the bootstrap JSON shown there as `bootstrap.json`, and set `device_id` as described in [Device identity](#user-content-device-identity). Use this flow only to get the configuration. Run host setup with the command in [Step 4](#user-content-step-4-run-setup-on-the-new-host).

The public downloads do not include your tenant configuration.

{% code overflow="wrap" %}

```
C:\StepSecuritySetup\  
   Setup-Dmg.ps1  
   Invoke-DmgProvisioningWorker.ps1  
   Dmg.Provisioning.Execution.psm1  
   Dmg.Provisioning.Policy.psm1  
   Dmg.Provisioning.Windows.psm1  
   agent.msi  
   agent.msi.sha256.sig  
   bootstrap.json
```

{% endcode %}

### Step 2: Stage files on the master image <a href="#user-content-step-2-stage-files-on-the-master-image" id="user-content-step-2-stage-files-on-the-master-image"></a>

1. Copy the complete bundle into a protected local folder on the master.
2. Set the owner to SYSTEM or local Administrators, and restrict the folder and files to those accounts. Ordinary users must not be able to read the bootstrap file, MSI or signature, or change the scripts or their parent path.
3. Do not run the MSI or `Setup-Dmg.ps1` on the master, and do not attach the host installation action to image maintenance events.
4. Confirm that Dev Machine Guard is not installed on the master and that no Dev Machine Guard scheduled tasks exist.

{% hint style="warning" %}
Treat the image and bootstrap configuration as credential-bearing assets. If Dev Machine Guard is already installed on the master, contact StepSecurity before capturing the staged-only image. Copying the bundle beside an existing installation does not disable it.
{% endhint %}

#### Device identity <a href="#user-content-device-identity" id="user-content-device-identity"></a>

Use hostname identity in the tenant configuration (`bootstrap.json`):

```
"device_id": "{hostname}"
```

Each host is reported as one device, with its signed-in users listed under it. Host names must be unique among active hosts. Do not use:

* A shared literal device ID
* `{user}`
* A fixed `user_id`
* Disabled multi-user detection

### Step 3: Capture the image and configure host provisioning <a href="#user-content-step-3-capture-the-image-and-configure-host-provisioning" id="user-content-step-3-capture-the-image-and-configure-host-provisioning"></a>

1. Capture the image through your normal image process, including Sysprep. Dev Machine Guard setup needs no special Sysprep switch. Reopening the master for maintenance does not start Dev Machine Guard, as long as the master stays staged-only.
2. Create a Windows scripted action that runs separately as SYSTEM, using the command in [Step 4](#user-content-step-4-run-setup-on-the-new-host).
3. Attach the action to every host creation and reimage workflow. It must run after final naming and any domain or hybrid join, and before users are admitted. Copying files into the image does not configure this action.

**Nerdio Manager examples**

* **Nerdio Manager for Enterprise:** use the host creation stage after AVD host pool registration and before user access. Select individual execution.
  * [See Scripted actions overview](https://nmehelp.getnerdio.com/hc/en-us/articles/26124327585421-Scripted-actions-overview)
* **Nerdio Manager for MSP:** enable the setting that keeps hosts deactivated until scripted actions complete.
  * [See Drain Mode: Deactivate Hosts During Scripted Actions](https://nmmhelp.getnerdio.com/hc/en-us/articles/47430524053005-Drain-Mode-Deactivate-Hosts-During-Scripted-Actions)

Confirm the options available in your installed edition, and test that a failed setup keeps the host unavailable during the pilot.

### Step 4: Run setup on the new host <a href="#user-content-step-4-run-setup-on-the-new-host" id="user-content-step-4-run-setup-on-the-new-host"></a>

Run this command as a separate host action in the SYSTEM, 64-bit context. Keep its exit code and capture its JSON output. The platform timeout must be longer than the 900-second setup budget, with extra time for startup and result publication.

{% code overflow="wrap" %}

```
& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" `
  -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass `
  -File 'C:\StepSecuritySetup\Setup-Dmg.ps1' `
  -MsiPath 'C:\StepSecuritySetup\agent.msi' `
  -ConfigPath 'C:\StepSecuritySetup\bootstrap.json' `
  -SignaturePath 'C:\StepSecuritySetup\agent.msi.sha256.sig' `
  -TimeoutSeconds 900 -MaxAttempts 3
$setupExit = $LASTEXITCODE
exit $setupExit
```

{% endcode %}

{% hint style="info" %}
Unlike the standard Windows MSI deployment, which never spawns PowerShell, this flow runs a PowerShell provisioning script as SYSTEM. The script then installs the same signed MSI. If your EDR restricts PowerShell on session hosts, allow this script to run.
{% endhint %}

Setup verifies the package and local configuration, runs the MSI as needed, and checks the installed runtime, identity and scheduled tasks. It does not download missing files, reboot the host or enable host pool access.

### Step 5: Check readiness before admitting users <a href="#user-content-step-5-check-readiness-before-admitting-users" id="user-content-step-5-check-readiness-before-admitting-users"></a>

Admit users only when the exit code is `0` and the JSON output has `status: "ready"`. Then complete your normal AVD readiness checks. A healthy rerun can return `action: "noop"`.

| Exit code               | What to do                                                                                                                                                                       |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`                     | Locally ready. Continue your platform's admission checks.                                                                                                                        |
| `10` or `30`            | Keep the host unavailable. Fix the reported input, trust, installation or readiness failure.                                                                                     |
| `20`                    | The installer or setup is busy. Schedule a bounded retry.                                                                                                                        |
| `40` or no final result | Completion is uncertain. Do not start another installer blindly. Investigate first. A pending operation from the same boot needs a controlled reboot before a fresh setup check. |
| `50`                    | Keep the host unavailable. Perform a controlled reboot, then rerun setup.                                                                                                        |

{% hint style="info" %}
A successful installation does not prove that user telemetry has reached StepSecurity. Confirm telemetry during the pilot.
{% endhint %}

#### Troubleshooting <a href="#user-content-troubleshooting" id="user-content-troubleshooting"></a>

Use the `error_code`, `result_path` and `log_path` values from the JSON output. Diagnostic files are written to:

{% code overflow="wrap" %}

```
%ProgramData%\StepSecurityProvisioning\<attempt_id>
```

{% endcode %}

{% hint style="warning" %}
This folder also contains private configuration copies. Share only the diagnostics StepSecurity requests, after you review them.
{% endhint %}

### Step 6: Validate the pilot <a href="#user-content-step-6-validate-the-pilot" id="user-content-step-6-validate-the-pilot"></a>

Before you expand the rollout, create a pilot host through your provisioning tool and confirm that:

* Setup succeeds before users are admitted.
* Two concurrent users each produce telemetry under the correct host in StepSecurity.
* Returning users keep their identity.
* A setup failure keeps the host unavailable.

Also test a healthy rerun, an automatic update cycle, and your normal master update and reimage cycle.

### Maintain the image <a href="#user-content-maintain-the-image" id="user-content-maintain-the-image"></a>

* Installed hosts update through Dev Machine Guard's normal automatic updater. Keep automatic updates enabled. See [Automatic Updates (Windows MSI)](https://docs.stepsecurity.io/developer-machines/installation/script/mdm-deployment/windows/automatic-updates-windows-msi.md).
* The MSI staged on the master does not update itself. During image maintenance, replace the staged bundle with a newly approved bundle so future hosts start from that version.
* With `{hostname}` identity, a replacement host that uses the same name gets the same device identifier. Avoid overlapping active hosts with the same name, and agree on this behavior with StepSecurity during the pilot.
* Rerunning the provisioning script does not change an existing host's identity.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stepsecurity.io/developer-machines/installation/script/azure-virtual-desktop-avd.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
