Installing Buildkite Agent on Windows
The Buildkite Agent is supported on Windows 8, Windows Server 2012, and newer. There are two installation methods: automated using PowerShell, and manual installation.
On this page:
Automated install with PowerShell
You'll need to run the automated installer within PowerShell with administrative privileges.
Once you're in an escalated PowerShell session, you can run this script to install the latest version of the agent:
PS> $env:buildkiteAgentToken = "<your_token>" PS> Set-ExecutionPolicy Bypass -Scope Process -Force iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/buildkite/agent/main/install.ps1'))
- Download the latest Windows release from Buildkite Agent releases on GitHub
- Extract the files to a directory of your choice (we recommend
buildkite-agent.cfgand add your agent token
buildkite-agent.exe startfrom a command prompt
SSH key configuration
Copy or generate SSH keys into your
.ssh directory. For example, typing the following into Git Bash generates a new private key which you can add to your source code host:
$ ssh-keygen -t rsa -b 4096 -C "email@example.com"
See the Agent SSH Keys documentation for more details.
- Agent Hooks:
- SSH keys:
The configuration file is located at
C:\buildkite-agent\buildkite-agent.cfg. See the configuration documentation for an explanation of each configuration setting.
There are two options to be aware of for this initial setup:
- Set your agent token, if you did not set it as an environment variable during installation.
You may need to use the
shellconfiguration option. On Windows, Buildkite defaults to using Batch. If you want to use PowerShell or PowerShell Core, you must point Buildkite to the correct shell. For example, to use PowerShell:
Using PowerShell Core (PowerShell 6 or 7) causes unusual behavior around pipeline upload. Refer to Defining steps: pipeline.yml file for details.
Rerun the install script.
Git for Windows
While the agent will work without Git installed, you will require Git for Windows to interact with Git. You will need Git Bash to use SSH on Windows 7 or below.
Buildkite does not currently support using Git Bash to run Bash scripts as part of your pipeline.
Running as a service
The simplest way to run buildkite-agent as a service is to use a third-party tool like nssm. Once installed, you can either run the GUI and configure manually, or create the service using the command-line:
# These commands assume you installed the agent using PowerShell # Your paths may be different if you did a manual installation nssm install buildkite-agent "C:\buildkite-agent\bin\buildkite-agent.exe" "start" nssm set buildkite-agent AppStdout "C:\buildkite-agent\buildkite-agent.log" nssm set buildkite-agent AppStderr "C:\buildkite-agent\buildkite-agent.log" nssm status buildkite-agent # Expected output: SERVICE_STOPPED nssm start buildkite-agent nssm status buildkite-agent
Installing Buildkite on Windows Subsystem for Linux 2
You can use Buildkite on Windows through WSL2. This gives you a way to work with Buildkite on Windows using a Bash shell. This can be useful, as many plugins use Bash.
To install the agent on WSL2, follow the generic Linux installation guide. Do not use the guides for Ubuntu, Debian, and so on, even if that is the Linux distro you are using with WSL2.
Using WSL2 causes unusual behavior during pipeline upload. Refer to Defining steps: pipeline.yml file for details.