Practical reference for installing, re-installing, and removing a self-hosted Azure DevOps agent on Linux and Windows in unattended mode. Covers agent pools, deployment groups, and environment VM resources.

• Prerequisites
• Linux — Agent Pool
• Windows — Agent Pool
• Deployment Group (Linux & Windows)
• Environment VM Resource (Linux & Windows)
• Unattended config — full flag reference
• Remove / Re-install
• Troubleshooting

1. Agent pool (for pipeline agents) — Project Settings → Agent pools → Add pool

   • Type: Self-hosted
   • Name: e.g. MyDodiTech-PRD
   • Grant access permission to all pipelines

2. Deployment group (for classic release pipelines) — Pipelines → Deployment groups → New

   • Name: e.g. MyDodiTech-PRD-DG
   • Note the project name — you need it for --projectName

3. Environment (for YAML pipelines) — Pipelines → Environments → New environment

   • Resource type: Virtual machines
   • Follow the registration script — or use the flags below for unattended setup

4. PAT (Personal Access Token) — User settings (avatar) → Personal access tokens → New Token

   • Scope: Agent Pools → Read & Manage (also covers deployment groups/environments)
   • Copy the token — it is shown only once

The agent ships its own .NET runtime — no separate .NET install needed.

mkdir -p ~/azagent && cd ~/azagent

AGENT_URL=$(curl -s https://api.github.com/repos/microsoft/azure-pipelines-agent/releases/latest \
  | grep browser_download_url \
  | grep linux-x64 \
  | cut -d '"' -f 4 \
  | head -1)

curl -fsSL "$AGENT_URL" -o agent.tar.gz
tar xzf agent.tar.gz
rm agent.tar.gz

cd ~/azagent

./config.sh \
  --unattended \
  --url https://dev.azure.com/<YOUR_ORG> \
  --auth pat \
  --token <YOUR_PAT> \
  --pool "<YOUR_POOL_NAME>" \
  --agent "$(hostname)" \
  --replace \
  --acceptTeeEula

cd ~/azagent

# Install the service running as your own user (replace ddt25 with your username)
sudo ./svc.sh install ddt25

# Start it
sudo ./svc.sh start

# Verify it is running
sudo ./svc.sh status

Why specify your username?
The agent needs to access your app directories (e.g. /home/ddt25/infrastructure/...). Running the service as ddt25 avoids all permission errors in the CD pipeline. Never run the agent service as root.

Project Settings → Agent pools → <YOUR_POOL_NAME> → Agents tab

The agent should show as Online.

Run all setup commands from an elevated PowerShell window. Never use PowerShell ISE or git-bash (mintty).

New-Item -ItemType Directory -Force -Path C:\agents
# Download the latest windows-x64 agent from https://github.com/microsoft/azure-pipelines-agent/releases
# Then extract:
Add-Type -AssemblyName System.IO.Compression.FileSystem
[System.IO.Compression.ZipFile]::ExtractToDirectory("$env:USERPROFILE\Downloads\vsts-agent-win-x64-*.zip", "C:\agents")

Keep the agent folder path free of spaces. C:\agents is recommended. Restrict folder permissions: only admins and the service account should have write access.

cd C:\agents

.\config.cmd `
  --unattended `
  --url https://dev.azure.com/<YOUR_ORG> `
  --auth pat `
  --token <YOUR_PAT> `
  --pool "<YOUR_POOL_NAME>" `
  --agent "$env:COMPUTERNAME" `
  --replace `
  --runAsService `
  --windowsLogonAccount "DOMAIN\svc-azagent" `
  --windowsLogonPassword "<SERVICE_ACCOUNT_PASSWORD>"

Prefer a dedicated domain account or gMSA over built-in accounts. The account only needs the permissions your pipeline tasks require — do not use an admin account.

The agent installs itself as a Windows service named:

vstsagent.<org-name>.<agent-name>

Check it from PowerShell:

Get-Service "vstsagent.*"

Or open services.msc and look for Azure Pipelines Agent / VSTS Agent.

Project Settings → Agent pools → <YOUR_POOL_NAME> → Agents tab — the agent should show as Online.

Deployment groups are used by classic release pipelines to target a specific set of machines.

cd ~/azagent

./config.sh \
  --unattended \
  --url https://dev.azure.com/<YOUR_ORG> \
  --auth pat \
  --token <YOUR_PAT> \
  --deploymentGroup \
  --deploymentGroupName "<YOUR_DG_NAME>" \
  --projectName "<YOUR_PROJECT_NAME>" \
  --agent "$(hostname)" \
  --replace \
  --acceptTeeEula \
  --addDeploymentGroupTags \
  --deploymentGroupTags "web,app"

sudo ./svc.sh install ddt25
sudo ./svc.sh start

cd C:\agents

.\config.cmd `
  --unattended `
  --url https://dev.azure.com/<YOUR_ORG> `
  --auth pat `
  --token <YOUR_PAT> `
  --deploymentGroup `
  --deploymentGroupName "<YOUR_DG_NAME>" `
  --projectName "<YOUR_PROJECT_NAME>" `
  --agent "$env:COMPUTERNAME" `
  --replace `
  --addDeploymentGroupTags `
  --deploymentGroupTags "web,app" `
  --runAsService `
  --windowsLogonAccount "DOMAIN\svc-azagent" `
  --windowsLogonPassword "<PASSWORD>"

Environment resources are used by YAML pipelines (environment: + resourceType: VirtualMachine).

cd ~/azagent

./config.sh \
  --unattended \
  --url https://dev.azure.com/<YOUR_ORG> \
  --auth pat \
  --token <YOUR_PAT> \
  --pool "<YOUR_POOL_NAME>" \
  --agent "$(hostname)" \
  --replace \
  --acceptTeeEula \
  --addvirtualmachineresourcetags \
  --virtualmachineresourcetags "web,app"

sudo ./svc.sh install ddt25
sudo ./svc.sh start

cd C:\agents

.\config.cmd `
  --unattended `
  --url https://dev.azure.com/<YOUR_ORG> `
  --auth pat `
  --token <YOUR_PAT> `
  --pool "<YOUR_POOL_NAME>" `
  --agent "$env:COMPUTERNAME" `
  --replace `
  --addvirtualmachineresourcetags `
  --virtualmachineresourcetags "web,app" `
  --runAsService `
  --windowsLogonAccount "DOMAIN\svc-azagent" `
  --windowsLogonPassword "<PASSWORD>"

Environment VM resources are registered through the agent pool — they appear in the environment after the agent connects and the environment's VM resource is linked.

Any flag can also be set as an environment variable by uppercasing it and prepending VSTS_AGENT_INPUT_.
Example: VSTS_AGENT_INPUT_TOKEN instead of --token.

cd ~/azagent

# 1. Stop and uninstall the service
sudo ./svc.sh stop
sudo ./svc.sh uninstall

# 2. Unregister from Azure DevOps
./config.sh remove --unattended --auth pat --token <YOUR_PAT>

# 3. Re-register with new settings
./config.sh \
  --unattended \
  --url https://dev.azure.com/<YOUR_ORG> \
  --auth pat \
  --token <YOUR_PAT> \
  --pool "<YOUR_NEW_POOL_NAME>" \
  --agent "$(hostname)" \
  --replace \
  --acceptTeeEula

# 4. Re-install and start the service
sudo ./svc.sh install ddt25
sudo ./svc.sh start
sudo ./svc.sh status

cd C:\agents

# 1. Remove agent (stops and uninstalls the service automatically)
.\config.cmd remove --unattended --auth pat --token <YOUR_PAT>

# 2. Re-register with new settings
.\config.cmd `
  --unattended `
  --url https://dev.azure.com/<YOUR_ORG> `
  --auth pat `
  --token <YOUR_PAT> `
  --pool "<YOUR_NEW_POOL_NAME>" `
  --agent "$env:COMPUTERNAME" `
  --replace `
  --runAsService `
  --windowsLogonAccount "DOMAIN\svc-azagent" `
  --windowsLogonPassword "<PASSWORD>"

sudo ./svc.sh install [username]   # Create systemd service (run as username)
sudo ./svc.sh start                # Start the service
sudo ./svc.sh stop                 # Stop the service
sudo ./svc.sh status               # Show service status
sudo ./svc.sh uninstall            # Remove the systemd service

Always use ./svc.sh instead of systemctl directly — pool names with special characters (hyphens, dots) are escaped by systemd and the raw unit name is hard to type correctly.