Create self-hosted on-premise Azure DevOps pipeline agent

zure devops self hosted agent creation

Azure DevOps supports deployment of the builds from release pipelines to the on-premise environments using self-hosted pipeline agents. This article describes how to create and configure a self-hosted Azure DevOps agent in an on-premise Windows machine.


  1. Azure DevOps account with owner permissions on the organization.
  2. Windows machine with OS versions supported are 7, 8.1, 10, Windows 2008 R2 SP1 or higher. And .Net Framework 4.6.2 or higher.


Microsoft made it very easy to create Azure DevOps self-hosted agent in an on-premise environment. This section describes how to do it.

Create Agent pool and download the agent

Follow the below steps to create agent pool in Azure DevOps and download the agent.

  1. Open Azure DevOps portal and navigate to the organization where you want to add the agent.
  2. Click on Organization settings.
  3. Click on Agent pools under the pipelines.
  4. Click on Add pool.
  5. Select Pool type as Self-hosted and provide a suitable name (say OnPremAgentPool). And click Create.
  6. Click on the newly created Agent pool (OnPremAgentPool) and Click on the New agent button.
  7. Click on the Download button under the Windows tab to download the agent pool zip file. This is the server where you want to create an on-premise Agent pool.

Configure the agent

Once you have downloaded the zip file, follow the below instruction to configure the agent in an on-premise machine.

  1. Navigate to the organization in the DevOps portal and click on the user settings icon at the top-right corner of the page. Click on Personal access tokens from the drop-down menu. Click on New Token. For the scope, select Agent Pools (read, manage) and make sure all the other boxes are unchecked. Once the token is created, copy and store the token for future use.
    The on-premise agent will use this token to communicate with Azure DevOps organization.
  2. Open PowerShell ISE on the Windows machine and execute the below command.
cd C:\ #base location for the agent folder. You can set it as per your needs.
mkdir agent
cd agent
Add-Type -AssemblyName System.IO.Compression.FileSystem ; [System.IO.Compression.ZipFile]::ExtractToDirectory("$HOMEDownloadsvsts-agent-win-x64-2.187.2.zip", "$PWD")

3. Navigate to the folder path C:\agent.
4. Double click on config.cmd file. This will open a cmd prompt with below questions.

Enter server URL > https://dev.azure.com/<organisation name>/
Enter authentication type (press enter for PAT) > <Press enter>
Enter personal access token > <Enter acces token generated in step 1>
If the connection is successful, it will ask you to register agent.
Enter agent pool (press enter for default) > <Name of the agent pool created earlier (OnPremAgentPool)>
Enter agent name (press enter for <servername>) > <Provide any suitable name for the agent. Default is Server name>
It will connect and test the agent connection. If it is successful,
Enter work folder (press enter for _work) > <press enter>
Enter run agent as service? (Y/N) (press enter for N) > (Enter Y if you want to run this as a service)
Enter configure autologon and run agent on startup? (Y/N) (press enter for N) > (Enter Y if you want to start the service on startup)

Congratulations, you have setup the agent!

Start and Verify the agent

1. Navigate to the folder path C:\agent.
2. Double click on run.cmd file. This will open a cmd prompt and connect to the server. After the successful connection, it will start listening for jobs.
3. You can go back to the Agent pools in Azure DevOps organization and see your agent status as online.

Agent is now ready to use in Release pipelines for on-premise deployments.

Spread the love

Kunal Rathi

Been working on the Microsoft BI stack for close to a decade. Aspiring Data Architect, Cloud enthusiast.

Leave a Reply

Your email address will not be published. Required fields are marked *