Machine runner installation on Linux
On This Page
- Download the machine runner launch-agent script
- Create the circleci user and working directory
- Create the working directory and set permissions
- Create the CircleCI’s self-hosted runner configuration
- Configure SELinux policy (RHEL 8)
- Start machine runner
- Machine runner configuration example
- Enable the systemd unit
- Start the service
- Verify the service is running
This page describes how to install CircleCI’s machine runner on Linux.
|This page is a continuation of installing self-hosted runners. You will need to have an existing CircleCI namespace and resource class to continue below. You can do this on the CircleCI web app by navigating to Self-Hosted Runners (see the documentation for the Web app installation). You can also use the CLI.|
Download the machine runner launch-agent script
Save the launch-agent.sh script file to an easily accessible location. From that location, install the launch-agent binary for your target platform, either x86_64, ARM64, s390x or ppc64le:
curl https://raw.githubusercontent.com/CircleCI-Public/runner-installation-files/main/download-launch-agent.sh --output ./download-launch-agent.sh
chmod +x ./download-launch-agent.sh
# For Linux x86_64: export platform=linux/amd64 && sh ./download-launch-agent.sh
# For Linux ARM64: export platform=linux/arm64 && sh ./download-launch-agent.sh
# For Linux s390x: export platform=linux/s390x && sh ./download-launch-agent.sh
# For Linux ppc64le: export platform=linux/ppc64le && sh ./download-launch-agent.sh
After successful installation, the download-launch-agent.sh file can be deleted.
circleci user and working directory
These will be used when executing the task-agent. These commands must be run as a user with permissions to create other users (e.g.
root). For information about GECOS, see the wiki page.
id -u circleci &>/dev/null || sudo adduser --disabled-password --gecos GECOS circleci
id -u circleci &>/dev/null || sudo adduser -c GECOS circleci
Create the working directory and set permissions
sudo mkdir -p /var/opt/circleci
sudo chmod 0750 /var/opt/circleci
sudo chown -R circleci /var/opt/circleci /opt/circleci
Consider running the following additional command if you would like to use certified orbs, without errors, that work on Cloud on your self-hosted runner. Note that this enables code to execute root commands on your machine, and changes to the system may persist after the job is run.
echo "circleci ALL=(ALL) NOPASSWD:ALL" | sudo tee -a /etc/sudoers
Create the CircleCI’s self-hosted runner configuration
launch-agent-config.yaml file with a path of
/etc/opt/circleci/launch-agent-config.yaml, owned by
circleci, with permissions
600. Use the following commands:
sudo mkdir -p /etc/opt/circleci && sudo touch /etc/opt/circleci/launch-agent-config.yaml
sudo chown -R circleci: /etc/opt/circleci
sudo chmod 600 /etc/opt/circleci/launch-agent-config.yaml
Copy the following to the new
api: auth_token: AUTH_TOKEN # On server, set url to the hostname of your server installation. For example, # url: https://circleci.example.com runner: name: RUNNER_NAME working_directory: /var/opt/circleci/workdir cleanup_working_directory: true
AUTH_TOKENwith the resource class token created in the set up process.
RUNNER_NAMEwith the name you would like for your self-hosted runner.
RUNNER_NAMEis unique to the machine that is installing the runner.
RUNNER_NAMEcan be any value you would like, and it does not need to include any part of your namespace or resource class name. However, it is recommended to use the hostname of the machine so that it can be used to identify the agent when viewing statuses and job results in the CircleCI web app. The only special characters accepted in RUNNER_NAME are
. () - _.
Configure SELinux policy (RHEL 8)
An SELinux policy is required for self-hosted runner to accept and launch jobs on RHEL 8 systems (earlier versions of RHEL are unsupported). Note that this policy does not add any permissions to the ones that may be required by individual jobs on this self-hosted runner install.
/etc/opt/circleci/policy and generate the initial policy module:
sudo mkdir -p /etc/opt/circleci/policy
# Install sepolicy and rpmbuild if you haven't already sudo yum install -y policycoreutils-devel rpm-build
sudo sepolicy generate --path /etc/opt/circleci/policy --init /opt/circleci/circleci-launch-agent
Download the following type enforcing file
circleci_launch_agent.te and install the policy:
sudo curl https://raw.githubusercontent.com/CircleCI-Public/runner-installation-files/main/rhel8-install/circleci_launch_agent.te --output /etc/opt/circleci/policy/circleci_launch_agent.te
Start machine runner
You can now start machine runner as follows:
sudo /opt/circleci/circleci-launch-agent --config /etc/opt/circleci/launch-agent-config.yaml
You can also optionally run machine runner as a systemd service.
Machine runner configuration example
The fields you must set for a specific job to run using your self-hosted runners are:
Simple example of how you could set up a job:
version: 2.1 workflows: build-workflow: jobs: - runner jobs: runner: machine: true resource_class: <namespace>/<resource-class> steps: - run: echo "Hi I'm on Runners!"
The job will then execute using your self-hosted runner when you push the config to your VCS provider.
|This step is optional.|
You will need to have systemd version 235+ installed for this optional step.
/usr/lib/systemd/system/circleci.service owned by
root with permissions
sudo touch /usr/lib/systemd/system/circleci.service
sudo chown root: /usr/lib/systemd/system/circleci.service
sudo chmod 755 /usr/lib/systemd/system/circleci.service
You must ensure that
TimeoutStopSec is greater than the total amount of time a task will run for, which defaults to 5 hours.
If you want to configure the CircleCI’s self-hosted runner installation to start on boot, it is important to note that machine runner will attempt to consume and start jobs as soon as it starts, so it should be configured appropriately before starting. Machine runner may be configured as a service and be managed by
systemd with the following scripts:
[Unit] Description=CircleCI Runner After=network.target [Service] ExecStart=/opt/circleci/circleci-launch-agent --config /etc/opt/circleci/launch-agent-config.yaml Restart=always User=circleci NotifyAccess=exec TimeoutStopSec=18300 [Install] WantedBy = multi-user.target
Unlike task-agents, which use the environment of the
circleci user, launch-agents will need to have any required environment variables (e.g., proxy settings) explicitly defined in the unit configuration file. These can be set by
EnvironmentFile=. Please visit the
systemd documentation for more information.
You can now enable the service:
sudo systemctl enable circleci.service
Start the service
When the CircleCI’s self-hosted runner service starts, it will immediately attempt to start running jobs, so it should be fully configured before the first start of the service.
sudo systemctl start circleci.service
Verify the service is running
The system reports a very basic health status through the
status field in
systemctl. This will report Healthy or Unhealthy based on connectivity to the CircleCI APIs.
You can see the status of the agent by running:
systemctl status circleci.service --no-pager
Which should produce output similar to:
circleci.service - CircleCI Runner Loaded: loaded (/var/opt/circleci/circleci.service; enabled; vendor preset: enabled) Active: active (running) since Fri 2020-05-29 14:33:31 UTC; 18min ago Main PID: 5592 (circleci-launch) Status: "Healthy" Tasks: 8 (limit: 2287) CGroup: /system.slice/circleci.service └─5592 /opt/circleci/circleci-launch-agent --config /etc/opt/circleci/launch-agent-config.yaml
You can also see the logs for the system by running:
journalctl -u circleci
Refer to the Troubleshoot Machine Runner section of the Troubleshoot Self-hosted Runner guide if you encounter issues installing or running machine runner on Linux.
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.
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.