Azure DevOps Agent

A lightweight, self-hosted Azure DevOps build agent based on Linux — available across multiple distributions and variants:

Tag prefix	Base	libicu	Description
trixie-*	debian:trixie-slim	76	Debian-based build
noble-*	ubuntu:noble (24.04 LTS)	74	Ubuntu-based build

Note: These images are intentionally minimal — they include only what is required to run the Azure DevOps agent (git, curl, ca-certificates, and .NET runtime libraries). No Python, Node.js, or other build tools are pre-installed. See Extending the image below.

---

🚀 Quick Start

Launch the agent with automatic restart:

Debian Trixie

docker run -d \
  --name doa-agent-prod \
  --restart unless-stopped \
  -e DO_URL="https://dev.azure.com/your-organization" \
  -e DO_PAT="your_personal_access_token" \
  -e DO_POOL="your_pool_name" \
  -e DO_AGENT_NAME="DOA-Agent" \
  karfee111/do-agent:trixie-latest

Ubuntu Noble

docker run -d \
  --name doa-agent-prod \
  --restart unless-stopped \
  -e DO_URL="https://dev.azure.com/your-organization" \
  -e DO_PAT="your_personal_access_token" \
  -e DO_POOL="your_pool_name" \
  -e DO_AGENT_NAME="DOA-Agent" \
  karfee111/do-agent:noble-latest

Monitor startup logs and registration:

docker logs -f doa-agent-prod

---

⚙️ Configuration Variables

The container automatically configures and registers the agent at boot using these environment variables:

Variable	Description	Default	Required
DO_URL	Full URL of your Azure DevOps organization	—	✅
DO_PAT	Personal Access Token with Agent Pools (Read & Manage) scope	—	✅
DO_POOL	Name of the target agent pool	Default	❌
DO_AGENT_NAME	Display name in the Azure DevOps panel	DOA-Agent-$(hostname)	❌

---

💓 Healthcheck

To ensure accurate container health monitoring without adding unnecessary overhead or packages, the native Linux /proc filesystem virtual directory is used to safely track the core Agent.Listener lifecycle. A start_period of 3 minutes is recommended to allow the ./start.sh entrypoint script to safely download updates and register with Azure DevOps before monitoring begins.

Docker Run Example

To deploy with health monitoring via CLI:

docker run -d \
  --name doa-agent-prod \
  --restart unless-stopped \
  -e DO_URL="https://dev.azure.com/your-organization" \
  -e DO_PAT="your_personal_access_token" \
  -e DO_POOL="your_pool_name" \
  -e DO_AGENT_NAME="DOA-Agent" \
  --health-cmd='grep -aq "Agent.Listener" /proc/[0-9]*/cmdline || exit 1' \
  --health-interval=45s \
  --health-timeout=10s \
  --health-retries=4 \
  --health-start-period=180s \
  karfee111/do-agent:noble-latest

---

📦 Docker Compose

services:
  azure-agent:
    image: karfee111/do-agent:trixie-latest
    container_name: doa-agent-prod
    restart: unless-stopped
    environment:
      - DO_URL=https://dev.azure.com/your-organization
      - DO_PAT=your_personal_access_token
      - DO_POOL=your_pool_name
      - DO_AGENT_NAME=DOA-Agent
    healthcheck:
      test: ["CMD-SHELL", "grep -aq 'Agent.Listener' /proc/[0-9]*/cmdline || exit 1"]
      interval: 45s
      timeout: 10s
      retries: 4
      start_period: 180s

docker compose up -d

Ubuntu variant: replace the tag with noble-latest to use the Ubuntu 24.04 based image.

---

🛠️ Pass-through Arguments

This image forwards extra arguments directly to Microsoft's native run.sh. For example, to run a single job and exit:

docker run -d \
  --name doa-agent-once \
  -e DO_URL="https://dev.azure.com/your-organization" \
  -e DO_PAT="your_personal_access_token" \
  -e DO_POOL="your_pool_name" \
  -e DO_AGENT_NAME="DOA-Agent" \
  karfee111/do-agent:trixie-latest --once

---

🔧 Extending the Image

These images ship with the bare minimum to run the agent. If your pipelines require additional tools (Python, Node.js, .NET SDK, etc.), extend the image with your own Dockerfile:

FROM karfee111/do-agent:trixie-latest

USER root

RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

USER agent

Alternatively, you can override the entrypoint at runtime to install packages or run setup commands dynamically before the agent starts.

⚠️ Important: When overriding the entrypoint, you must end your execution chain with exec ./start.sh.

Via Docker Run:

docker run -d \
  --name doa-agent-prod \
  --restart unless-stopped \
  -e DO_URL="https://dev.azure.com/your-organization" \
  -e DO_PAT="your_personal_access_token" \
  -e DO_POOL="your_pool_name" \
  -e DO_AGENT_NAME="DOA-Agent" \
  --entrypoint /bin/bash \
  karfee111/do-agent:trixie-latest \
  -c "apt-get update && apt-get install -y --no-install-recommends python3 && ln -sf /usr/bin/python3 /usr/bin/python && exec ./start.sh"

Via Docker Compose:

services:
  azure-agent:
    image: karfee111/do-agent:trixie-latest
    restart: unless-stopped
    entrypoint: >
      /bin/bash -c "
      apt-get update && 
      apt-get install -y --no-install-recommends python3 && 
      ln -sf /usr/bin/python3 /usr/bin/python && 
      exec ./start.sh
      "
    environment:
      - DO_URL=https://dev.azure.com/your-organization
      - DO_PAT=your_personal_access_token
      - DO_POOL=your_pool_name
      - DO_AGENT_NAME=DOA-Agent

Tip: For production use, prefer extending via Dockerfile rather than runtime installation — it keeps startup fast, independent of external package mirrors, and fully reproducible.

---

🏷️ Tag Convention

trixie-{agent_version}.{build_number}       # Debian Trixie
noble-{agent_version}.{build_number}        # Ubuntu 24.04 LTS

Examples: trixie-4.274.1.1, noble-4.274.1.1

latest Tags

Tag	Points to
trixie-latest	most recent trixie-* build
noble-latest	most recent noble-* build
latest	global alias pointing to the most recent noble-* build

Floating tags always resolve to the most recent build for their respective distribution or the global default.