Set Up AVD Hybrid (On-Premises Session Hosts)

Step-by-step setup for Azure Virtual Desktop Hybrid with Atlas AVD: prepare your on-premises Windows machines, connect them to Azure Arc, and more.

Before you begin

  • A tenant in Azure Commercial or Microsoft 365 GCC. AVD Hybrid isn't available in GCC High yet, because Microsoft hasn't confirmed the AVD Arc extension in Azure Government
  • Windows Server 2016, 2019, 2022 or 2025, or Windows 10/11 Enterprise (single-session) machines on your own infrastructure. Windows 10/11 Enterprise multi-session isn't supported on AVD Hybrid
  • Outbound HTTPS from each machine to the Azure Virtual Desktop required URLs and the Azure Arc network endpoints
  • Owner or User Access Administrator on the subscription that will hold the Arc machines, so you can register resource providers and, if needed, create role assignments
  • An existing resource group in the subscription Atlas is connected to, to hold the new host pool
  • In Atlas, the Manage host pools permission to open the AVD Hybrid page, and the host pool provisioning permission to create a pool and add machines to it (the Operator and Administrator roles include both)
  • Licensing: an Azure Virtual Desktop Hybrid service license for each user, plus the operating system entitlement (see the next section)

What you do and what Atlas does

AVD Hybrid splits the work between your infrastructure and Azure. Atlas automates the Azure steps it has permission for and shows you the exact command when a step has to be done by hand.

  • You: build and patch the Windows machines, join them to your domain, connect them to Azure Arc, and manage their power, hardware and images with your own tools.
  • Atlas: creates the on-premises host pool with a managed identity and a desktop application group, and can add it to a workspace. No virtual machines or networks are created.
  • Atlas: lists every Arc-enabled machine it can see, flags the ones that can't be used and why, and checks that the host pool's identity has Reader access on the machines' resource groups. It grants that access for you when it's allowed to.
  • Atlas: gets a fresh registration key for the pool and installs the AVD Arc extension on the machines you pick.
  • After that, the hosts appear on the host pool's page in Atlas like any other session host, and users connect with Windows App.

Check operating system, sign-in and licensing requirements

Microsoft supports AVD Hybrid on the following systems. Atlas checks the operating system that Azure Arc reports and marks anything unsupported as Not eligible, but domain join and licensing are yours to confirm.

  • Windows Server 2016, 2019, 2022 and 2025: virtual machines or headless physical servers. The machine must be joined to Active Directory Domain Services (or hybrid joined); Microsoft Entra-only join isn't supported, because Windows Server needs an RDS licensing server. Users need RDS Client Access Licenses with Software Assurance, or RDS User Subscription Licenses.
  • Windows 10 and 11 Enterprise (single-session): virtual machines, or physical machines only when they are dedicated, headless, rack-mounted hosts. Laptops and personal PCs aren't supported. Entra joined, AD DS joined, and hybrid joined are all supported. Users need Microsoft 365 E3/E5/A3/A5/F3 or Business Premium, Windows Enterprise E3/E5, Windows Education A3/A5, or Windows VDA per user.
  • Windows 10 and 11 Enterprise multi-session: not supported on AVD Hybrid.
  • In addition to the operating system entitlement, each user needs an Azure Virtual Desktop Hybrid service license from Microsoft.

Step 1: Build and prepare the on-premises machines

Deploy the machines with whatever you already use (your hypervisor's tools, Configuration Manager, scripts, or a partner tool), join them to your domain, and size them for the number of users you expect. Then make sure each machine can reach Azure: it needs outbound HTTPS (port 443) to the Azure Virtual Desktop required URLs for session hosts and to the Azure Arc network endpoints for Arc-enabled servers. If you use a proxy or firewall, allow both lists before you continue.

Install-WindowsFeature -Name RDS-RD-Server -Restart

On Windows Server, the AVD Arc extension installs the Remote Desktop Session Host role and restarts the machine if the role isn't already there. To control when that restart happens, install the role yourself first with the command below, during your own maintenance window.

Step 2: Register the Azure resource providers

In the subscription that will hold the Arc machines, register the resource providers Azure Arc and AVD need. This is a one-time step per subscription. In the Azure portal, open the subscription, select Settings → Resource providers, and register each provider below; or run the commands in Azure Cloud Shell. Registration takes a few minutes.

az account set --subscription "<subscription-id>"
az provider register --namespace Microsoft.HybridCompute
az provider register --namespace Microsoft.GuestConfiguration
az provider register --namespace Microsoft.HybridConnectivity
az provider register --namespace Microsoft.AzureArcData
az provider register --namespace Microsoft.DesktopVirtualization

Put the Arc machines in the same subscription Atlas is connected to, in a resource group that holds only your AVD Hybrid machines (for example rg-avd-hybrid-onprem). Atlas can only see Arc machines in subscriptions its app registration can read, and the role assignments in the steps below are scoped to that one resource group.

Step 3: Connect each machine to Azure Arc

Install the Azure Connected Machine agent on every machine so it appears in Azure as an Arc-enabled server.

  1. In the Azure portal, search for Azure Arc and open it. Under Infrastructure, select Machines.
  2. Select Add/Create, then Add a machine. Choose to add a single server (or multiple servers, which uses a service principal for unattended installs) and select Generate script.
  3. Choose the subscription and the resource group from Step 2, a region, and Windows as the operating system. Set the connectivity method to match your network (public endpoint or proxy).
  4. Run the generated script on each machine in an elevated PowerShell session.
  5. Back in Azure Arc → Machines, confirm each machine shows a status of Connected.

On the machine itself, run azcmagent show to see the agent status, and azcmagent check to test the Arc network endpoints. A machine that shows Disconnected or Expired can't receive the AVD extension; reconnect it before continuing.

Step 4: Let Atlas install the AVD extension on your Arc machines

To add machines from the AVD Hybrid page, the Atlas app registration (named AtlasAVD in your directory) needs permission to install extensions on the Arc machines: the Azure Connected Machine Resource Administrator role. Atlas's setup script grants it on the subscription Atlas is connected to, so if your Arc machines are in that subscription and you set Atlas up (or re-ran the setup script) after AVD Hybrid gained this check, there's nothing to do. Otherwise assign the role on the resource group that holds your Arc machines. You don't have to guess: when the role is missing, the AVD Hybrid page shows an "Atlas needs permission to add these machines" banner listing the resource groups and the exact command to run, and marks those machines Not eligible.

  1. In the Azure portal, open the resource group that holds your Arc machines and select Access control (IAM) → Add → Add role assignment.
  2. Search for Azure Connected Machine Resource Administrator, select it, and select Next.
  3. For Assign access to, choose User, group, or service principal, then Select members and search for AtlasAVD, the app registration Atlas signs in with. If you created it under another name, search for that name or its application (client) ID.
  4. Select Review + assign twice.
az role assignment create \
  --assignee "<atlas-application-client-id>" \
  --role "Azure Connected Machine Resource Administrator" \
  --scope "/subscriptions/<subscription-id>/resourceGroups/<arc-machines-resource-group>"

If you also want Atlas to give the host pool's identity Reader access on this resource group for you in Step 6, the AtlasAVD app registration needs permission to assign roles there too (for example User Access Administrator, or Role Based Access Control Administrator, on the resource group). Without it, Atlas shows you the one command to run instead. Role assignments can take a few minutes to apply. If you'd rather not grant Atlas any of this, install the extension yourself (see Alternative: install the extension in Azure, below).

Step 5: Create an on-premises host pool in Atlas

Hybrid hosts join a host pool that has no Azure VMs in it. Create a dedicated one from the AVD Hybrid page. In Atlas, open Workspace → AVD Hybrid in the sidebar (it sits directly under Host Pools), then click Create on-premises host pool at the top of the page.

  1. Host Pool Name (required): the Azure name of the pool, up to 64 characters using letters, digits, '.', '_', '-', '(', ')' or '+'.
  2. Friendly Name (optional): the name users see in Windows App. If you leave it blank, the host pool name is used.
  3. Resource Group (required): an existing resource group in the Azure subscription Atlas is connected to. Atlas doesn't create it, so create it in Azure first if you need a new one.
  4. Region (required): the Azure region that stores the host pool's metadata, written as its short name (for example eastus or westeurope). It doesn't have to match where your machines are.
  5. Host Pool Type: Pooled (several users share each host) or Personal (each user gets their own host). For a Pooled pool, also choose the Load Balancer (Breadth First spreads users across hosts, Depth First fills one host before starting the next) and Max Sessions per host (10 by default).
  6. Workspace: pick an existing AVD workspace to publish the pool's desktop to your users, or leave Don't add to a workspace and do it later.
  7. Click Create on-premises host pool. A Host pool created message confirms it's ready for your on-premises machines.

Atlas creates the host pool with a system-assigned managed identity and its desktop application group, with Start VM on Connect off. No virtual machines, virtual networks, network security groups or NAT gateways are created. If you see Host pool created with warnings, the pool exists but the application group or the workspace link couldn't be set up; the message gives Azure's reason, and you can finish that part in the Azure portal. The pool counts toward your plan's host pool limit.

Step 6: Add the machines to the host pool

The AVD Hybrid page lists every Arc-enabled machine the Atlas app registration can see, with four totals across the top: Arc-enabled machines, Ready to onboard, Onboarded, and Not eligible. The Getting started panel on the right summarizes these same steps.

  1. Click Refresh if you've just connected machines to Arc; the list is read from Azure Resource Graph and can lag a minute or two behind the Azure portal.
  2. Check the Eligibility column. Ready machines can be selected; Not eligible machines show the reason underneath (see Troubleshooting).
  3. Tick the machines you want (up to 50 at a time), then click Add to host pool.
  4. In the Add machines to a host pool dialog, choose the host pool you created in Step 5. Pools that already contain Azure VMs are listed as Has Azure VMs and can't be picked. If you skipped Step 5, click Create on-premises host pool in the dialog; the new pool is selected for you when it's created.
  5. Check the Host pool access to these machines panel. It lists each resource group that holds the selected machines as Reader granted or Reader missing. If any show Reader missing, click Grant access: Atlas turns on the pool's managed identity if needed and assigns it the Reader role. If Atlas isn't allowed to assign roles in a resource group, the panel shows the az role assignment create command to run in Azure Cloud Shell instead; run it, then click the refresh icon to check again.
  6. If any selected machine runs Windows Server, tick I understand that Windows Server machines may restart.
  7. Click Add machines. Atlas re-checks every machine in Azure, gets a fresh registration key for the pool, and installs the AVD Arc extension on each machine. The registration key is passed to Azure as a protected setting and is never stored or logged by Atlas.

An Onboarding started message confirms which machines are joining the pool. If some machines couldn't be added, a second message lists each one with the reason; the others still go ahead. Microsoft has said a future release will keep session hosts from becoming Available unless the host pool's identity has Reader on the machines' resource group, so grant it now even though adding machines isn't blocked without it.

Step 7: Confirm the hosts are Available and connect

Installing the extension and registering with the pool takes a few minutes per machine.

  1. On the AVD Hybrid page, the AVD extension column moves from Installing to Installed. Hover over a Failed status to see Azure's message.
  2. Allow up to 15 minutes after the extension shows Installed for the host to report Available. Microsoft documents this delay.
  3. Open Host Pools, select the pool, and check that each host is listed and Available. The pool carries an On-premises badge, and hosts are listed under their Arc machine name (FQDN).
  4. Assign users or groups to the pool's desktop application group from the host pool's page in Atlas, if you haven't already.
  5. Have one of those users sign in with Windows App. The desktop appears in the same workspace feed as any other AVD resource.

To monitor these hosts in Atlas, install the Atlas Endpoint Agent on them yourself: Atlas installs it automatically only on Azure VMs it deploys. The agent supports Windows Server 2019 or later and Windows 10/11, so Windows Server 2016 hosts run without it.

Alternative: install the extension in Azure

If you'd rather not give Atlas the role in Step 4, add machines from the Azure portal instead. Open Azure Arc → Machines, select the machine, then Settings → Extensions → Add. Choose Azure Virtual Desktop Hybrid, select the subscription, resource group and host pool from Step 5, and select Review + Create, then Create. Or use Azure PowerShell, which needs the Az.DesktopVirtualization and Az.ConnectedMachine modules. The hosts then show up on the pool's page in Atlas after its next Azure sync, and on the AVD Hybrid page as Onboarded. Grant the pool's identity Reader on the machines' resource group yourself in this case (Access control (IAM) → Add role assignment → Reader → Managed identity → Host pool).

$expires = (Get-Date).ToUniversalTime().AddHours(4).ToString("yyyy-MM-ddTHH:mm:ss.fffffffZ")
$reg = New-AzWvdRegistrationInfo -ResourceGroupName "<host-pool-resource-group>" -HostPoolName "<host-pool-name>" -ExpirationTime $expires

New-AzConnectedMachineExtension `
  -Name "Microsoft.AzureVirtualDesktop.CloudDeviceExtension" `
  -ResourceGroupName "<arc-machines-resource-group>" `
  -MachineName "<arc-machine-name>" `
  -Location "<arc-machine-region>" `
  -Publisher "Microsoft.AzureVirtualDesktop" `
  -ExtensionType "CloudDeviceExtension" `
  -ProtectedSetting @{ registrationToken = $reg.Token }
$hostPool = Get-AzWvdHostPool -Name "<host-pool-name>" -ResourceGroupName "<host-pool-resource-group>"
New-AzRoleAssignment -ObjectId $hostPool.IdentityPrincipalId -RoleDefinitionName "Reader" -ResourceGroupName "<arc-machines-resource-group>"

What works for on-premises hosts in Atlas

Azure doesn't manage the state of on-premises machines, so Microsoft doesn't support power management, autoscale, Start VM on Connect or Session Host Configuration for AVD Hybrid. Atlas follows the same rules.

  • Works as usual: the host pool page, drain mode, active sessions, log off, disconnect and send message, user and group assignments, application groups and RemoteApp, and the workspace.
  • Not available: power on/off and power schedules, autoscale and Azure scaling plans, Start VM on Connect, reimage, image rollout and host replacement, VM resize, disk tiering, adding Azure VMs to the pool, deleting the machine, and Azure VM run commands.
  • Atlas's background jobs (autoscale, auto-reimage, image rollout, disk tiering and density scale-out) skip AVD Hybrid pools entirely.
  • Deleting the host pool removes the hosts' registration from it but never deletes your Arc machines or anything on your infrastructure.

Some of these buttons still appear on an AVD Hybrid pool's page today. If you click one, Atlas declines with a message that the operation isn't available for on-premises (Azure Virtual Desktop Hybrid) session hosts, and nothing changes. Manage power, patching and images with your own infrastructure tools.

Keep Azure VMs and on-premises hosts in separate pools

A pool created with Create on-premises host pool is an on-premises pool from the start. Atlas also treats any other pool as an AVD Hybrid pool as soon as one of its session hosts is an Azure Arc machine, and that can't be undone: power management, autoscale, reimage and the other Azure VM operations are switched off for every host in it, including Azure VMs. That's why the Add machines dialog only offers pools that are empty or already on-premises. Don't add Azure VMs to an on-premises pool either; use a separate pool for them.

Troubleshooting

  • AVD Hybrid is missing from the sidebar: you need the Manage host pools permission, and the AVD Hybrid preview must be switched on for the tenant (it's on by default and can be turned off on the Preview step of first-run setup).
  • Create on-premises host pool or Add to host pool is missing: you need the host pool provisioning permission (Operator or Administrator role).
  • Not available in this cloud: the tenant is in GCC High (Azure Government), where AVD Hybrid stays off until Microsoft confirms the AVD Arc extension there. Use Azure-hosted session hosts instead.
  • Could not create the host pool: the message gives the reason. A pool with that name already exists in the resource group, the resource group doesn't exist, the region name isn't one Azure recognizes, or your plan's host pool limit has been reached.
  • No Arc-enabled machines were found: the machines aren't connected to Arc yet, or they're in a subscription the Atlas app registration can't read. Move them to the subscription Atlas is connected to, or give the AtlasAVD app registration Reader on their resource group, then click Refresh.
  • Not a Windows machine / Windows multi-session is not supported on AVD Hybrid / Only Windows Server and Windows 10/11 Enterprise are supported: the machine's operating system can't be used. See the requirements above.
  • The Arc agent is disconnected, or The Arc agent has expired: run azcmagent show on the machine, fix its connectivity, or reconnect it to Azure Arc.
  • The AVD extension is already installed: the machine is already a session host. To move it to another pool, remove the extension and the session host in Azure first.
  • The operating system could not be identified: older Arc agents don't always report the edition. You can still add the machine; Azure checks the OS when the extension runs.
  • Atlas is not allowed to install extensions in this machine's resource group, or adding fails with an authorization error mentioning Microsoft.HybridCompute: complete Step 4, wait a few minutes for the role assignment to apply, then click Refresh.
  • Reader missing stays after Grant access: Atlas can't assign roles in that resource group. Run the command the panel shows, wait a minute, and check again.
  • Could not get a registration token for the host pool: the Atlas app registration needs Desktop Virtualization Contributor on the host pool's subscription. Re-run the Atlas setup script or assign the role in Azure.
  • The AVD extension shows Failed: hover over it for Azure's message. The usual causes are blocked AVD URLs or an unsupported operating system. Fix the cause, then select the machine and add it again; Atlas retries the install.
  • Installed, but the host isn't Available after 15 minutes: check that the pool's identity has Reader on the machines' resource group (Step 6), that a Windows Server host is AD DS or hybrid joined rather than Entra-only joined, and that the machine can still reach the AVD URLs.

Next steps