Azure DevOps Self-Hosted Agent: Complete Step-by-Step Setup Guide 2026

An Azure DevOps self-hosted agent allows you to run CI/CD pipelines on your own infrastructure instead of relying on Microsoft-hosted build agents. This is especially important for Power Platform, SharePoint, and enterprise deployments where Microsoft-hosted parallelism is limited or unavailable.

If you have encountered the error “No hosted parallelism has been purchased or granted”, setting up a self-hosted agent in Azure DevOps is the fastest and most reliable way to unblock your pipelines.

If you are new to Azure DevOps pipelines, I recommend starting with my Azure DevOps CI/CD Pipeline: Azure Pipelines Overview, Architecture, and Best Practices to understand how build agents, pipelines, and stages work together.

This guide explains how to perform a complete Azure DevOps agent pool setup and connect it to your CI/CD pipelines in a secure, production-ready way.

What Is an Azure DevOps Self-Hosted Agent?

A self-hosted agent in Azure DevOps is a machine that executes pipeline jobs on your behalf. Instead of running on Microsoft’s shared infrastructure, your pipelines run on:

• Your own Windows laptop
• An on-premises server
• An Azure virtual machine

This machine becomes your Azure DevOps pipeline agent, responsible for building, packaging, and deploying your applications.

Because the agent is fully controlled by you, it is ideal for:

• Power Platform CI/CD
• Dataverse deployments
• SharePoint automation
• Secure enterprise networks

Why Enterprises Use Azure DevOps Build Agents Instead of Microsoft-Hosted Agents

Microsoft-hosted agents are convenient, but they come with strict limits. A self-hosted Azure DevOps build agent removes these restrictions.

For Power Platform, where pipelines must access Dataverse, APIs, and corporate networks, a self-hosted agent Azure DevOps is the industry standard.

Prerequisites for Azure DevOps Agent Pool Setup

Before configuring an Azure DevOps self-hosted agent, you must have an active Azure DevOps organization. If you don’t have one yet, follow my step-by-step guide on how to create an organization in Azure DevOps.

You also need an Azure DevOps project where the agent pool and pipelines will be configured. I’ve covered this in detail in my article on how to create a project in Azure DevOps.

Before you configure your Azure DevOps self-hosted agent, make sure you have:

• An active Azure DevOps organization
• An Azure DevOps project
• A Windows machine (Windows 10, Windows 11, or Windows Server)
• Permission to manage agent pools in Azure DevOps

Step 1 – Azure DevOps Agent Pool Setup

The first step is creating a dedicated pool that will hold your self-hosted agents.

1. Open Azure DevOps

2. Go to Organization Settings

3. Select Agent Pools

4. Click Add Pool

5. Choose:

   • Pool type: Self-hosted

   • Name: SelfHosted-Windows

6. Click Create

Once you click the Add pool button, select Self-hosted as the pool type, enter a name for your Azure DevOps self-hosted agent pool, and then click Create to create the pool.

This pool defines where your Azure DevOps pipeline agent will run.

Step 2 – Download the Azure DevOps Build Agent

1. Open the Self-Hosted-agent pool (you just created)

2. Click New Agent

3. Select:

   • OS: Windows

   • Architecture: x64

4. Download the agent ZIP file

5. Extract it to:

   C:\AzureDevOpsAgent


This folder contains the software that turns your machine into an Azure DevOps build agent.

The above steps are shown in the below screenshots:

Step 3: How to Generate a Personal Access Token (PAT) in Azure DevOps

A Personal Access Token (PAT) is required to authenticate your Azure DevOps self-hosted agent and allow it to connect securely to your organization.

Steps to create a PAT

1. Open your Azure DevOps organization
   https://dev.azure.com/<your-organization-name>

2. Click your profile icon in the top-right corner.

3. Select User settings → Personal access tokens.

4. Click + New Token.

5. Configure the token:

   • Name: Self-Hosted-Agent-PP

   • Organization: Select your Azure DevOps org

   • Expiration: 90 days (or longer if allowed)

   • Scopes (click “Show all scopes”):

     • Agent Pools → Read & manage

     • Deployment Groups → Read & manage

     • Pipeline Resources → Use

6. Click Create and copy the token.

You will paste this token when running config.cmd while setting up your Azure DevOps self-hosted agent.

⚠️ The token is shown only once, so store it securely.

The above steps are shown in the below screenshots:

Screen 1: Click on the “Personal access token” link

Screen 2: Configure parameters for personal access token creation

Screen 3: Copy the personal access token.

Note:

• The personal access token is needed in the below section while configuring the self-hosted agent in your local machine.
• Read this warning message: “Warning – Make sure you copy the above token now. We don’t store it and you will not be able to see it again.”

Step 3 – Configure the Self-Hosted Agent Azure DevOps

Open PowerShell as Administrator in the extracted folder and run:

I have opened PowerShell as administrator and located the agent installation zip folder.

Provide the following values when it asks:

Step / Prompt	Value Entered	Notes / Explanation
Server URL	https://dev.azure.com/GlobalSharePoint	The Azure DevOps organization URL where the agent will connect
Authentication type	PAT (default)	Personal Access Token authentication
Personal Access Token	************	Used to authenticate the agent securely
Agent pool	GlobalSP-SelfHosted	The self-hosted agent pool where this agent will register
Agent name	PP-Agent-01	Friendly name of the agent; appears in Azure DevOps UI
Work folder	_work (default)	Folder on the machine where builds and pipeline jobs will run
Run agent as service	Y	Configures the agent to run automatically as a Windows service
Enable SERVICE_SID_TYPE_UNRESTRICTED	N (default)	No unrestricted service SID needed; safe default
User account for service	NT AUTHORITY\NETWORK SERVICE (default)	Built-in Windows account to run the service securely
Prevent service starting immediately	N (default)	The agent service starts automatically after configuration
Final service status	Started successfully	Confirms the agent is online and ready in the pool

Once completed, your machine becomes an active Azure DevOps self-hosted agent.

Here is the complete configuration that I have passed during the PowerShell command execution:

Step 4 – Verify the Azure DevOps Pipeline Agent

Go to:

Organization Settings → Agent Pools → GlobalSP-SelfHosted

You should see your agent marked as Online.

In case if you see agent status is not online run the below command from the same path:

PS C:\Users\User\Downloads\AzureDevOpsAgent\vsts-agent-win-x64-4.266.2> .\run.cmd

This confirms that your Azure DevOps pipeline agent is ready to execute jobs.

Step 5 – Connect the Self-Hosted Agent to Your Pipeline

To use your self-hosted agent, update your pipeline YAML.

Replace this:

With this:

Now every pipeline run will execute on your Azure DevOps build agent instead of Microsoft-hosted infrastructure.

Why Self-Hosted Agents Are Critical for Power Platform

Power Platform pipelines require:

• Dataverse access
• PAC CLI
• Power Platform Build Tools
• Secure Azure AD authentication

Microsoft-hosted agents reset after every run.
A self-hosted agent Azure DevOps provides:

• Persistent tools
• Faster deployments
• Private network access
• Enterprise-grade security

This is how organizations deploy Power Apps, Power Automate flows, and Copilot Studio agents safely and reliably.

PowerShell Commands for Troubleshooting Azure DevOps Self-Hosted Agent

After installing and configuring the Azure DevOps self-hosted agent, you may occasionally face issues such as the agent showing Offline, pipelines not picking the agent, or services not starting correctly. The following PowerShell commands help you quickly troubleshoot and fix common problems.

⚠️ Always run PowerShell as Administrator and navigate to the agent installation directory before executing these commands.

Example agent path:

C:\azagent

Restart the Azure DevOps Agent Service

If the agent appears Offline or does not respond to pipeline jobs, restarting the agent service usually resolves the issue.

This command:

• Stops the agent service
• Restarts it cleanly
• Reconnects the agent to Azure DevOps

Check Agent Service Status

To confirm whether the agent service is running:

Expected result:

• Running → Agent is active

• Stopped → Agent is not running and needs to be started

Run Agent in Interactive Mode (Debugging)

If you want to run the agent in interactive mode to see detailed logs in real time:

Use this when:

• Agent connects but jobs fail immediately
• You want verbose console output for debugging

⚠️ Stop the Windows service first before running in interactive mode.

Remove the Agent Configuration (Safe Cleanup)

If the agent configuration becomes corrupted or you want to re-register the agent:

This will:

• Unregister the agent from Azure DevOps
• Remove service bindings
• Keep files intact for reconfiguration

You can then re-run:

Conclusion: Azure DevOps Self-Hosted Agent

Thus, in this article, we have learned how to create a self-hosted pool and how to create a self-hosted agent and configure it step by step.

An Azure DevOps self-hosted agent is the foundation of reliable enterprise CI/CD. It removes Microsoft parallelism limits, gives you full control over your deployment environment, and enables secure Power Platform and SharePoint automation.

Whether you are building Power Apps or deploying Dataverse solutions, a self-hosted Azure DevOps build agent ensures your pipelines always run when you need them.

About Post Author