Azure DevOps supports self-hosted agents when your pipeline jobs need to run on machines that you manage, such as servers in an on-premises network, private network, or custom build environment. A self-hosted agent runs the Azure Pipelines agent software and executes jobs from an agent pool.
Quick answer: Create a self-hosted agent pool in Azure DevOps, download the current agent package for your operating system, configure the agent with an Azure DevOps-supported registration method, and run it as a service when you need it available continuously. For new Windows installations, use a supported operating system and the current Azure Pipelines agent version.
When should you use a self-hosted agent?
Self-hosted agents are useful when pipeline jobs need access to resources that Microsoft-hosted agents cannot reach or when you need to control the machine, installed software, network connectivity, or build environment. For example, a self-hosted agent can run inside a private network that has access to internal servers or other protected resources.
- Deploy to resources in an on-premises or private network.
- Use software, SDKs, tools, or configuration that is not available on Microsoft-hosted agents.
- Use a persistent build environment that you manage.
- Meet network or security requirements that require the pipeline job to execute inside your environment.
Prerequisites:
1. An Azure DevOps organization and permission to create or manage agent pools and register an agent.
2. A Windows machine that meets the requirements of the current Azure Pipelines agent. Agent version 5 uses .NET 10, so the host operating system must support .NET 10. Microsoft is rolling out agent 5.x during 2026.
3. Outbound HTTPS connectivity from the agent to the Azure DevOps services and required endpoints. Azure DevOps documents port 443 and the current agent download endpoint at download.agent.dev.azure.com.
4. A registration method supported by your Azure DevOps environment. Azure DevOps Services supports PAT, service principal, and Microsoft Entra device code flow for agent registration.
Security note: An agent executes pipeline code, so treat a self-hosted agent as part of your trusted infrastructure. Microsoft recommends using a low-privileged account to run the agent and avoiding unnecessary access to secrets or production resources.
Create an agent pool and download the agent
Agent pools are organization-scoped collections of agents. A pipeline selects an agent pool, and Azure Pipelines chooses an available agent from that pool that satisfies the job’s demands.
- Open Azure DevOps and open your organization.
- Go to Organization settings > Agent pools.
- Select Add pool.
- Choose Self-hosted, enter a pool name, and create the pool.
- Open the new pool and select New agent.
- Select the appropriate operating system and download the current agent package.
Available on Microsoft Store
SSRS Reports Migration Wizard
A simple Windows tool for migrating SSRS reports, data sources, and related configurations between report servers.
Configure the Azure DevOps self-hosted agent
Extract the downloaded agent package into a dedicated directory on the Windows machine. For example:
mkdir C:\agent
cd C:\agent
Extract the downloaded ZIP into this directory. Then run config.cmd from an elevated command prompt or PowerShell session and follow the prompts.
cd C:\agent
.\config.cmd
Choose the registration authentication method
During configuration, enter your Azure DevOps organization URL, select an authentication method supported by your environment, and provide the required credentials. For Azure DevOps Services, Microsoft currently supports PAT, service principal, and Microsoft Entra device code flow for agent registration. PAT registration requires the Agent Pools (read, manage) scope.
If you use a PAT, treat it as a secret. Do not place it in scripts, source control, screenshots, or documentation. Use the narrowest scope required and rotate or revoke the token according to your organization’s security policy.
Continue through the configuration prompts for the agent pool name, agent name, and work folder. The default work folder is _work.
Run the agent as a Windows service
For a server that should accept pipeline jobs continuously, configure the agent to run as a service during setup or install it as a service after configuration. Running the agent as a service avoids requiring an interactive user session to keep the agent available.
During Windows agent configuration, select the option to run the agent as a service when prompted. This is the appropriate way to keep a Windows self-hosted agent available without requiring an interactive user session.
Start and verify the self-hosted agent
After configuration, start the agent or its Windows service. Return to Organization settings > Agent pools, open the pool, and select Agents. The new agent should appear and report Online when it is connected and ready to accept jobs.
You can also run the agent interactively for troubleshooting by starting run.cmd from the agent directory:
cd C:\agent
.\run.cmd
Once the agent is online, select the self-hosted pool in your YAML or classic pipeline job. The job will be assigned to an available agent in that pool that satisfies the pipeline’s demands.
Agent software version and operating-system support
Azure Pipelines is moving from the 4.x agent to the 5.x agent during 2026. Agent 5.x uses .NET 10. If an existing agent host cannot support .NET 10, upgrade the operating system before moving to agent 5.x. Microsoft notes that previous agent versions generally do not receive the same security patching as the current agent version.
Always check Microsoft’s current agent version 5 documentation before installing or upgrading an agent, because supported operating systems and agent requirements change over time.
Self-hosted agent security recommendations
- Run the agent under a low-privileged account rather than an account with broad administrative access.
- Keep agent machines isolated from unrelated production systems where possible.
- Use separate agent pools for projects with different trust boundaries when practical.
- Avoid running untrusted or forked pull-request builds on self-hosted agents unless the environment is specifically isolated for that purpose.
- Keep the agent software and operating system current.
- Allow only the required outbound network destinations and use HTTPS.
Troubleshooting
- Agent is offline: verify that the agent service or
run.cmdprocess is running and that the machine can reach Azure DevOps over HTTPS. - Agent cannot download updates: check firewall and proxy rules, including the current Azure DevOps agent download endpoint.
- Authentication fails: verify that the selected registration method is supported and that the identity or PAT has the required permissions.
- Pipeline cannot find the agent: confirm that the pipeline uses the correct agent pool and that the agent’s capabilities satisfy the job demands.
- Agent upgrade fails: check whether the host operating system supports the agent version being installed, particularly the .NET 10 requirement for agent 5.x.
Pro tips:
1. For new installations, start with the current agent version and verify the host operating system against Microsoft’s supported list.
2. Prefer a low-privileged service account for the agent and isolate self-hosted agents according to the trust level of the pipelines they execute.
3. If your pipeline must access a private network, place the agent where it has the required network connectivity rather than exposing the private resource publicly.
4. If you use a PAT for registration, give it only the required Agent Pools scope and treat it as a secret.
A self-hosted Azure DevOps agent gives your pipelines control over the execution environment and network connectivity. For production use, combine the agent with current software, least-privilege permissions, appropriate network controls, and a pool design that matches the trust boundaries of your projects.
See more
Visual Studio Marketplace
SSIS Catalog Migration Wizard
Extend Visual Studio with an easy way to migrate SSIS Catalog projects.
Kunal Rathi
With over 15 years of experience in data engineering and analytics, I've assisted countless clients in gaining valuable insights from their data. As a dedicated supporter of Data, Cloud and DevOps, I'm excited to connect with individuals who share my passion for this field. If my work resonates with you, we can talk and collaborate.
