☁️ Introduction
When you run pipelines in Azure DevOps, they use agents — machines that execute our build or deployment steps.
Microsoft provides free Microsoft-hosted agents, but they can be slow, have limited parallelism, and reset after every run.
That’s where self-hosted agents come in. We can install an agent on our own machine (Windows, Linux, or macOS) and use it for faster, more controlled, and offline builds.
In this post, we’ll:
✅ Set up a self-hosted agent in Azure DevOps
✅ Run a simple “Hello World” pipeline using that agent
🧩 Prerequisites
✅ Azure DevOps Project
You’ll need an Azure DevOps Organization and project.
If you don’t have one, follow the post Getting Started with Azure DevOps Organization.
✅ Repository in Azure DevOps Repos
Create a new repository to store your pipeline YAML file.
You can name it, for example: cocan-agent-demo.
Refer to Getting Started with Azure Repos if needed.
✅ Machine for Self-Hosted Agent
You’ll need a machine (Windows, Linux, or macOS) that can stay online during your builds.
You can use an Ubuntu Virtual Machine (VM) created in Azure for this purpose.
Follow the post How to Create an Ubuntu VM in Azure to create and configure the VM.
When you create, select SSH based authentication instead of password.
We also do not need a public IP. When you use a Linux (Ubuntu) VM as a self-hosted Azure DevOps agent, the agent connects outbound to Azure DevOps — it’s the one initiating the connection. Azure DevOps never connects back into the VM. If you need to log in later, use Azure Bastion or temporarily assign a public IP.
✅ Personal Access Token (PAT)
We’ll need a PAT to register your agent.
Go to your Azure DevOps organization → User Settings icon (next to your profile picture on the top right) → Personal Access Tokens, create a new token (for example, agent-setup), and select Agent Pools (Read & manage) permission. Set the expiry to 90 days or more to avoid frequent reconfiguration.
🧩 Step 1: Create an Agent Pool
1️⃣ Go to your Azure DevOps Project → Project Settings → Agent Pools (Under Pipelines in the left sidebar)
2️⃣ Click Add pool
3️⃣ Enter a name like SelfHostedPool
4️⃣ Click Create
💡 Tip: You can reuse the same pool for multiple agents (for example, one on Windows and another on Linux).
🧩 Step 2: Download and Configure the Agent
Now, we’ll install the agent on your machine (for example, the Ubuntu VM you created in Azure).
🐧 For Linux (Ubuntu)
1️⃣ SSH into your Ubuntu VM.
2️⃣ Create a directory for the agent:
mkdir myagent && cd myagent
3️⃣ Download the agent package:
💡 Tip: Go to Azure DevOps → Project Settings → Agent Pools → New Agent → Linux,
then click the copy icon next to the Download button to get the latest download URL.
Example (version numbers may vary):
wget https://download.agent.dev.azure.com/agent/4.261.0/vsts-agent-linux-x64-4.261.0.tar.gz
4️⃣ Extract the agent package:
tar zxvf vsts-agent-linux-x64-4.261.0.tar.gz
5️⃣ Configure the agent:
./config.sh
You’ll be asked for:
Enter (Y/N) Accept the Team Explorer Everywhere license agreement now? (press Enter for N) > Y
Enter server URL > https://dev.azure.com/your-org-name
Enter authentication type (press Enter for PAT) > PAT
Enter PAT > <paste your token>
Enter agent pool (press Enter for default) > SelfHostedPool
Enter agent name (press Enter for ado-self-hosted-agent) > my-ubuntu-agent
Enter replace? (Y/N) (press Enter for N) > Y
Scanning for tool capabilities.
Connecting to the server.
Successfully added the agent
Testing agent connection.
Enter work folder (press Enter for _work) >
2025-10-31 16:27:52Z: Settings Saved.
6️⃣ Install and start the service:
sudo ./svc.sh install
sudo ./svc.sh start
7️⃣ (Optional) Run the agent interactively (if you didn’t install it as a service):
./run.sh
8️⃣ (Optional) Install common utilities for pipelines (for example, Terraform tasks):
sudo apt update && sudo apt install -y unzip curl jq✅ That’s it! Your self-hosted agent is now connected to Azure DevOps.
You can verify it by going to Azure DevOps → Project Settings → Agent Pools → SelfHostedPool,
where your agent’s status should show as Online 🟢.
🖥️ (Optional) For Windows
1️⃣ Go to Project Settings → Agent Pools → SelfHostedPool → New Agent
2️⃣ Select Windows and download the ZIP file.
3️⃣ Extract it to a folder such as C:\agents\myagent.
4️⃣ Open PowerShell as Administrator, then run:
cd C:\agents\myagent
.\config.cmd
5️⃣ Follow the prompts to enter the URL, PAT, and pool details.
6️⃣ Finally, install and start the service:
.\run.cmd
# OR
.\svc install
.\svc start
🧩 Step 3: Create a Simple “Hello World” Pipeline
Let’s test the agent with a very basic YAML pipeline.
📁 In your repository cocan-agent-demo, create the following structure:
cocan-agent-demo/
└── .azure-pipelines/
└── hello-world.yml
📄 .azure-pipelines/hello-world.yml
trigger:
- main
pool:
name: 'SelfHostedPool'
steps:
- script: echo "Hello World from Self-Hosted Agent!"
displayName: 'Print Hello World'
- script: |
echo "Current directory: $(System.DefaultWorkingDirectory)"
echo "Agent name: $(Agent.Name)"
displayName: 'Show Agent Info'
💡 Explanation:
- The pipeline runs whenever code is pushed to the
mainbranch. - The
poolpoints to your SelfHostedPool. - The steps simply print messages and display basic environment info.
🧩 Step 4: Create and Run the Pipeline in Azure DevOps
1️⃣ Go to Pipelines → New Pipeline
2️⃣ Choose Azure Repos Git
3️⃣ Select your repository cocan-agent-demo
4️⃣ Choose Existing Azure Pipelines YAML file
5️⃣ Browse to .azure-pipelines/hello-world.yml
6️⃣ Click Run
🎉 The pipeline will now run using your self-hosted agent!
Sample log output:
Hello World from Self-Hosted Agent!
Current directory: /home/azureuser/myagent/_work/1/s
Agent name: my-ubuntu-agent
🧩 Step 5: Troubleshooting Common Issues
💡 Agent not showing online?
Check network/firewall settings. Ensure the VM can reach dev.azure.com and that the agent service is running.
💡 Permission error when registering?
Make sure your PAT has Agent Pools (read, manage) permission.
💡 Pipeline stuck in queue?
Verify that:
- The agent is online
- It’s part of the SelfHostedPool used in the YAML file
🧹 Step 6: Clean Up (Optional)
If you no longer need the agent:
sudo ./svc.sh stop
sudo ./svc.sh uninstall
./config.sh remove
You can also delete the VM if it was created in Azure to save costs.
🔍 Why Use a Self-Hosted Agent?
✅ Faster builds (runs locally or on your own VMs)
✅ Full control over installed tools and dependencies
✅ Access to private network or on-prem resources
✅ No waiting for hosted agent availability
✅ Summary
✔️ Created an Ubuntu VM in Azure for hosting the self-hosted agent
✔️ Connected it to an Azure DevOps agent pool
✔️ Created a simple “Hello World” pipeline to verify functionality
✔️ Achieved faster, flexible, and secure CI/CD builds 🎯