Upgrading the CircleCI machine runner on cloud

Cloud

Checking current machine runner version

You can check the machine runner version by using the --version flag with the binary. The following are the default installation directories for the CircleCI machine runner binary:

Linux and macOS: /opt/circleci/circleci-launch-agent
Windows: C:\Program Files\CircleCI\circleci-launch-agent.exe

Enabling auto update

The most straightforward way to upgrade an existing CircleCI machine runner is to enable auto update in the configuration file and restart the runner instance. To enable auto update:

Remove the disable_auto_update option from the machine runner configuration file, or set runner.disable_auto_update to false.
Restart the machine runner instance with the process management used to manage the CircleCI machine runner agent. If process management is not being used to manage the machine runner, the instance will need to be manually stopped using kill -9 on macOS and Linux systems, or the Task Manager on Windows systems, and then manually restarted.

More details on configuring machine runner can be found in the machine runner configuration reference.

Linux

sudo systemctl restart circleci.service

macOS

sudo launchctl stop '/Library/LaunchDaemons/com.circleci.runner.plist'
sudo launchctl start '/Library/LaunchDaemons/com.circleci.runner.plist'

Windows

Stop-ScheduledTask -TaskName "CircleCI Launch Agent"
Start ScheduledTask -TaskName "CircleCI Launch Agent"

In some cases, an environment variable may have been used to disable the auto update functionality. If the machine runner installation is not updated after enabling auto update in the configuration file, set the value of the environment variable LAUNCH_AGENT_RUNNER_DISABLE_AUTO_UPDATE to false, or unset the variable entirely. Then, restart the machine runner instance again.

Manually update by downloading a new version of the machine runner binary

For machine runners where auto update cannot be used, the machine runner binary, also known as the launch-agent binary, can be manually downloaded and used to replace the existing version.

If process management is not being used to manage the machine runner, the process will need to be manually stopped using kill -9 on macOS and Linux systems, or the Task Manager on Windows systems, and then manually restarted.

The process to download the binary can be broken into three steps: downloading the binary, replacing the binary, and restarting the CircleCI machine runner service. These steps are expanded upon in the section below.

1. Download a new version of the binary

Download the binary on Linux or macOS

Set the platform environment variable

As with the Linux and macOS installation process, first you need to set the environment variable platform to the correct value for the target installation system.

# for Linux x86_64
export platform=linux/amd64

# for Linux ARM64
export platform=linux/arm64

# for Linux s390x
export platform=linux/s390x

# for Linux ppc64le
export platform=linux/ppc64le

# for macOS ARM64 (M1+ chips)
export platform=darwin/arm64

# for macOS x86_64
export platform=darwin/amd64

Download the new agent binary

# Download the new version of the CircleCI Agent manually on macOS, and Linux with bash
base_url="https://circleci-binary-releases.s3.amazonaws.com/circleci-launch-agent"
agent_version=$(curl "${base_url}/release.txt")
curl -sSL "${base_url}/${agent_version}/checksums.txt" -o checksums.txt
mkdir -p "${platform}"
file="$(grep -F "${platform}" checksums.txt | cut -d ' ' -f 2 | sed 's/^.//')"
curl --compressed -L "${base_url}/${agent_version}/${file}" -o "${file}"
grep "${file}" checksums.txt | sha256sum --check || echo "Failed to download the CircleCI machine runner binary, please try again"
chmod +x $file

Download the binary on Windows

# Download the new version of the CircleCI Agent manually on Windows with PowerShell
$Env:platform = "windows/amd64"
mkdir $Env:platform
$Env:baseURL =  "https://circleci-binary-releases.s3.amazonaws.com/circleci-launch-agent"
$Env:agentVersion = $(curl "$Env:baseURL/release.txt")
$Env:agentVersion = "$Env:agentVersion".Trim()
curl "$Env:baseURL/$Env:agentVersion/checksums.txt" -o checksums.txt
$Env:fileName = $(Select-String $Env:platform checksums.txt | cut -d ' ' -f 2 | sed 's/^.//')
$Env:fileName = $Env:fileName.Trim()
curl "$Env:baseURL/$Env:agentVersion/$Env:fileName" -o $Env:fileName
$Env:fileHash = $(Get-FileHash $Env:fileName -Algorithm "SHA256" | select -expand "Hash")
$Env:expectedHash = "$(grep $Env:filename checksums.txt)".Split(" ")[0]
if ($Env:expectedHash -ne $Env:fileHash) { Write-Output "CircleCI machine runner binary download failed, please try again"}else{Write-Output "CircleCI machine runner binary successfully downloaded to $CWD/$Env:fileName"}

2. Replace the existing binary with the new version

Replace the existing binary on Linux

sudo systemctl stop circleci.service
# Replace the current binary with the newly downloaded binary, by default the machine runner binary is installed to `/opt/circleci/circleci-launch-agent`

Replace the existing binary on macOS

sudo launchctl stop '/Library/LaunchDaemons/com.circleci.runner.plist'
# Replace the current binary with the newly downloaded binary, by default the machine runner binary is installed to `/opt/circleci/circleci-launch-agent`

Replace the existing binary on Windows

Stop-ScheduledTask -TaskName "CircleCI Launch Agent"
# Replace the current binary with the newly downloaded binary, this will require renaming or deleting the existing binary

3. Restart the machine runner service

Restart the machine runner service on Linux

sudo systemctl start circleci.service

Restart the machine runner service on macOS

sudo launchctl start '/Library/LaunchDaemons/com.circleci.runner.plist'

Restart the machine runner service on Windows

Start-ScheduledTask -TaskName "CircleCI Launch Agent"

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Suggest an edit to this page (please read the contributing guide first).
To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.