Windows hosted agents
Windows hosted agents are:
Buildkite agents hosted by Buildkite that run on Windows Server 2022 in ephemeral virtual machines.
Configured as part of a Buildkite hosted queue, where the machine type is Windows, with a particular size to efficiently manage jobs with varying requirements.
Windows hosted agents are currently in public preview and available on Trial, Pro, and Enterprise plans. To provide feedback, contact the Buildkite Support team at support@buildkite.com.
Learn more about:
Best practices for configuring queues in How should I structure my queues of the Clusters overview, as well as Manage queues.
How to configure Windows hosted agents in Create a Buildkite hosted queue.
The concurrency, security, and current limitations of Windows hosted agents.
Running GitHub Actions workflows on Windows hosted agents using GitHub Actions Compatibility.
Sizes
Windows hosted agents support the AMD64 architecture in four instance shapes:
| Instance shape | Size | Architecture | vCPU | Memory | |||||
|---|---|---|---|---|---|---|---|---|---|
| Instance shape |
WINDOWS_AMD64_2X8
|
Size | Small | Architecture | AMD64 | vCPU | 2 | Memory | 8 GB |
| Instance shape |
WINDOWS_AMD64_4X16
|
Size | Medium | Architecture | AMD64 | vCPU | 4 | Memory | 16 GB |
| Instance shape |
WINDOWS_AMD64_8X32
|
Size | Large | Architecture | AMD64 | vCPU | 8 | Memory | 32 GB |
| Instance shape |
WINDOWS_AMD64_16X64
|
Size | Extra Large | Architecture | AMD64 | vCPU | 16 | Memory | 64 GB |
The Extra Large (XL) instance shape is only available on Enterprise plans. Contact Buildkite Support to request access.
Base image
Windows hosted agents use a fixed, Buildkite-managed Windows Server 2022 base image. Windows hosted queues don't support the base image configuration available for Linux and macOS hosted queues. A Windows hosted queue's settings page doesn't display a Base Image tab.
Each job runs in a new virtual machine. After the job finishes, Buildkite destroys the virtual machine and its data.
Concurrency
Windows hosted agents can operate concurrently when running your Buildkite pipeline jobs.
This concurrency is measured by the number of hosted agent machines that are allocated for your jobs at any given time. A machine is counted from the moment it starts booting to acquire a job, since that's when the machine starts consuming capacity. As a result, concurrency may not always match the exact number of running jobs, particularly with short-lived workloads.
To calculate the maximum number of concurrent Windows hosted agents, divide your plan's Windows vCPU concurrency limit by the instance shape's vCPU count. See platform limits for the default limits for each plan.
For example, the WINDOWS_AMD64_4X16 (Medium) instance shape has a vCPU count of four. A Windows concurrency limit of 64 vCPU supports 16 concurrent agents of this shape.
Jobs that would exceed the limit remain queued until capacity becomes available.
Security
Each Windows job runs in an isolated virtual machine that Buildkite destroys, together with its data, after the job completes.
Current limitations
Windows hosted agents don't currently support:
- Custom base images
- Cache volumes
- Terminal access using SSH
- Desktop access using VNC or Remote Desktop
- ARM64 architecture
- Nested virtualization
- Windows Server 2025
- Selecting a Windows shell in the queue settings
- Selecting or managing the Buildkite agent version
Without nested virtualization, Windows hosted agents can't run WSL2, Docker Desktop, or Windows containers with Hyper-V isolation. Docker Engine is installed on the base image and runs Windows containers with process isolation.