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 private preview and must be enabled for your Buildkite organization. To request access, 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.
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 |
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.
The number of Windows hosted agents that can process jobs concurrently depends on the Windows vCPU concurrency allocated to your organization and the instance shape configured for the queue.
When a job would exceed the allocated concurrency, it remains queued until sufficient capacity is 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
- Windows Server 2025
- Selecting a Windows shell in the queue settings
- Selecting or managing the Buildkite agent version
- Windows jobs through the GitHub Actions compatibility feature