Docs
Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Upgrading the CircleCI’s self-hosted runner on server

2 months ago1 min read
Server v4.0 - v4.6
On This Page

This page describes how to update the CircleCI’s machine runner on CircleCI server installations.

Machine runner on server compatibility

Refer to the individual installation pages for machine runner to find the runner version you need for your platform:

Upgrading machine runner on server

Unlike CircleCI cloud, server does not automatically update the circleci-launch-agent, and requires manual intervention. The following sections detail how to upgrade machine runners in your server installation across all environments.

Upgrading machine runner in a containerized environment

This section details how to upgrade self-hosted runner in containerized environments: Kubernetes and Docker.

Upgrading machine runner for Kubernetes

Refer to the Kubernetes Installation Instructions.

Upgrading machine runner in Docker

  1. Stop any currently running self-hosted runner containers:

    docker stop <container-name>

  2. Remove the self-hosted runner containers:

    docker stop <container-name>; docker rm <container-name>;

  3. Start a new machine runner Docker container:

    CIRCLECI_RESOURCE_CLASS=<resource-class> CIRCLECI_API_TOKEN=<runner-token> agent_version=<agent_version_for_server> docker run --env agent_version --env CIRCLECI_API_TOKEN --env CIRCLECI_RESOURCE_CLASS --name <container-name> <image-id-from-previous-step>

Upgrading machine runner in a non-containerized environment

The process for manually updating the circleci-launch-agent binary can be broken down into three steps for non containerized environments. These steps are expanded upon in the sections below.

  1. Replace existing circleci-launch-agent binary with the new version.

  2. Stop currently running circleci-launch-agent processes.

  3. Start the new version of the circleci-launch-agent binary.

1. Replace the circleci-launch-agent-binary with the new version

Following the same step as in the individual platform installations, update the launch agent version environment variable to the correct version, then save and run the script to download and replace the old binary with the newly updated version.

export agent_version="<launch-agent-version>" && sh ./download-launch-agent.sh
$Env:agentVer = "<launch-agent-version>"
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;
./Install-CircleCIRunner.ps1

2. Stop the currently running machine runner

The currently running circleci-launch-agent process will need to be halted before starting the newly updated binary. Platform-specific instructions for this are given below.

Stopping the machine runner on Linux

Run the following commands:

sudo systemctl stop circleci.service
sudo systemctl disable circleci.service
Stopping the machine runner on Mac

Run the following commands:

sudo launchctl unload '/Library/LaunchDaemons/com.circleci.runner.plist'
Stopping the machine runner on Windows

Run the following command:

Stop-ScheduledTask -TaskName "CircleCI Launch Agent"

3. Start the new machine runner

Platform-specific instructions are given below.

Starting on Linux

Run the following commands:

sudo systemctl reload circleci.service
sudo systemctl enable circleci.service
sudo systemctl start circleci.service
Starting on Mac

Run the following command:

sudo launchctl load '/Library/LaunchDaemons/com.circleci.runner.plist'
Starting on Windows

Run the following commands:

Start-ScheduledTask -TaskName "CircleCI Launch Agent"

Additional resources

Suggest an edit to this page

Make a contribution
Learn how to contribute

Still need help?

Ask the CircleCI community
Join the research community
Visit our Support site