Skip to content

Set up a Build Agent

A self-hosted build agent runs the DevOps tasks defined in your pipeline. The recommended setup is a Windows host running Docker, hosting the Azure DevOps agent in a container.

Skip the infra: use ALOps Build Agents

Don't want to provision and maintain build hosts yourself? Our ALOps Build Agents are a managed offering — purpose-built, tuned for BC, and the fastest BC build agents available. Point your pipeline at them and skip the rest of this page.

Recommendations

A few guidelines before you provision the host.

Hardware

  • Dedicated and purpose-built. Use a server (or VM) reserved for build duty — don't co-locate other workloads.
  • Higher clock speed beats more cores. 4 cores at 4 GHz outperforms 16 cores at 2 GHz for typical BC build work.
  • 16 GB RAM or more.

Topology

  • One agent per host. Run a single Azure DevOps agent or GitHub runner per server — concurrent agents on the same host contend for Docker, disk, and CPU.
  • No HA, redundancy, or DR. Build agents are stateless and disposable; replace them rather than engineering for recovery, and save the cost.

Security

  • Don't domain-join. Leave the host standalone (workgroup) so a compromised build can't pivot into the domain.
  • Sandbox the network. Place the agent in a DMZ or isolated segment with only the egress it needs (Azure DevOps / GitHub, NuGet, container registries).
  • Skip antivirus, Defender, and SmartScreen. They slow builds significantly and frequently break Docker. Only acceptable because the host is standalone and DMZ-isolated — both conditions must hold.

Host preparation

We recommend Windows Server 2022 as the host OS.

  1. Install Windows Server 2022.
  2. Apply all available Windows updates and reboot.

  3. Enable the required Windows features:

    Install-WindowsFeature Hyper-V, Containers -Restart

  4. Install Docker (pinned version so updates can be tested before rollout, and rolled back if necessary):

    Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Confirm:$false -Force
Install-Module DockerProvider -Confirm:$false -Force
Install-Package Docker -RequiredVersion 19.03.2 -ProviderName DockerProvider -Confirm:$false -Force

  5. Reset the Containers feature so it picks Docker up correctly:

    Uninstall-WindowsFeature Containers
Restart-Computer -Force:$true -Confirm:$false

Install-WindowsFeature Containers
Restart-Computer -Force:$true -Confirm:$false

  6. Disable automatic Windows updates. Apply updates manually on a schedule, keeping rollback available.

ALOps dependencies

ALOps requires PowerShell 7 and the .NET SDK on the agent host.

PowerShell

Install PowerShell 7.6.0 or higher (see releases):

Invoke-WebRequest -Uri 'https://github.com/PowerShell/PowerShell/releases/download/v7.6.0/PowerShell-7.6.0-win-x64.msi' -OutFile 'PowerShell-7.6.0-win-x64.msi'
msiexec /i PowerShell-7.6.0-win-x64.msi /qn

.NET SDK

Install .NET SDK 8, 9 and 10 side-by-side:

Invoke-WebRequest -Uri 'https://dot.net/v1/dotnet-install.ps1' -OutFile 'dotnet-install.ps1'
.\dotnet-install.ps1 -Channel 8.0 -InstallDir "C:\Program Files\dotnet"
.\dotnet-install.ps1 -Channel 9.0 -InstallDir "C:\Program Files\dotnet"
.\dotnet-install.ps1 -Channel 10.0 -InstallDir "C:\Program Files\dotnet"

App signing (optional)

Only needed if your pipelines sign apps:

dotnet tool install --global --version 0.9.1-beta.25379.1 sign

Reboot

Reboot the agent host after installing PowerShell and the .NET SDK.