Running a self-hosted Azure Pipelines agent

Azure Pipelines runs your build and release steps on an agent. Microsoft-hosted agents are convenient — a fresh, managed machine for every run, with common tooling pre-installed and nothing for you to maintain. But they’re not always the right fit. When you need specific tooling, faster builds through caching, or connectivity to protected resources, a self-hosted agent gives you the control that a hosted one can’t.

This article covers when a self-hosted agent earns its keep, how to set one up, and how to keep it healthy.

When a self-hosted agent earns its keep

There are a few clear signals that it’s time to run your own agent:

• Custom tooling. You depend on SDKs, CLIs or custom tasks that aren’t on the hosted images and are slow to install on every run. A self-hosted agent has them ready.
• Private network access. Your pipeline needs to reach resources inside a private network or behind a firewall — a database, an internal service, an on-premises system. A self-hosted agent can live inside that network.
• Faster builds. Your builds benefit from a warm cache and persistent state between runs. Hosted agents start clean every time; a self-hosted agent can keep dependencies and build outputs around, cutting build times noticeably.
• Special hardware or OS. You need a configuration the hosted pool doesn’t offer.

If none of these apply, hosted agents are the simpler choice — don’t take on maintenance you don’t need. But when one or more of these is a recurring cost, a self-hosted agent pays for itself quickly.

Setting it up

The process is straightforward:

1. Provision a host — a machine or VM you control, with the tooling your pipelines need.
2. Create an agent pool in Azure DevOps (or use the default self-hosted pool).
3. Download and configure the agent on the host, registering it against your organisation and the pool using a personal access token or other supported credential.
4. Run the agent, typically as a service so it starts automatically and stays available.

Once registered, it behaves like any other agent. Your pipeline simply targets that pool, and the steps run in an environment you fully own — with exactly the tools, access and performance characteristics you’ve provisioned.

Scaling and availability

A single agent processes one job at a time. If your team runs many pipelines, you can register several agents in the same pool so jobs run in parallel rather than queueing. For elastic demand, agents can even run in containers or scale sets that grow and shrink with load — giving you hosted-style elasticity while keeping the control of self-hosting.

Keeping it healthy

The flip side of control is responsibility: a self-hosted agent is yours to maintain. A few habits keep it dependable:

• Patch and update. Keep the OS, the agent software and your tooling current, or builds slowly rot as versions drift.
• Watch disk space. Caching aggressively is great for speed, but caches grow. Clean up old build artifacts and working directories so the agent doesn’t fill its disk mid-build.
• Secure the machine. Because the agent can reach your protected resources and holds credentials, treat it as the sensitive infrastructure it is: least-privilege access, restricted network exposure, and careful handling of the token it registered with.
• Monitor it. Know when the agent is offline or unhealthy before a developer discovers it by way of a stuck pipeline.

The trade-off in a sentence

Hosted agents trade control for zero maintenance; self-hosted agents trade a little maintenance for control, speed and reach. For many Power Platform and Azure builds — especially those that need private connectivity or specific tooling — that trade is well worth making, and a well-run self-hosted agent is often noticeably faster than a cold hosted one to boot.