Migrate from launch agent to machine runner 3.0 on Linux

Cloud

Server v4.4+

Migrating from launch agent to machine runner 3.0 is a straightforward process. The prerequisites remain the same. First, uninstall and remove launch agent, then, install the machine runner 3.0 agent. The configuration file is 1:1 compatible between the agents so no modifications are needed during the migration

1. Uninstall launch agent

The first step is to uninstall launch agent. The exact process depends on the platform, as described in the following sections.

If the agent has been installed as a systemd service, run the following commands to stop and uninstall the service unit, and delete the service file (the new agent will install a new service unit):
```
sudo systemctl stop circleci.service
sudo systemctl disable circleci.service

sudo rm /usr/lib/systemd/system/circleci.service
```
The launch agent binary can now be removed from the machine. The default install location is /opt/circleci/circleci-launch-agent, but this may differ on your machine if the agent was installed somewhere else. The entire /opt/circleci subdirectory can be removed at this point.
Finally, move the agent configuration file. The default location for this is /etc/opt/circleci/launch-agent-config.yaml. Move the file to /etc/circleci-runner/circleci-runner-config.yaml using the following command:
```
mv /etc/opt/circleci/launch-agent-config.yaml /etc/circleci-runner/circleci-runner-config.yaml
```
Alternatively, you can let the machine agent install process create a config file template and copy the existing config into the newly created file.

RHEL/Rocky Linux

In addition to the steps listed above, the SELinux policy should be uninstalled using the following command:

sudo semodule -r circleci_launch_agent

2. Install the machine agent

Follow the instructions provided in Install machine runner 3.0 on Linux to install machine runner 3.0 using the provided packages.
The packages create template configuration files at /etc/circleci-runner/circleci-runner-config.yaml. This configuration is 1:1 compatible with the launch agent configuration, apart from the auto-update feature. Since auto-update has been removed from the new agent, you should use the appropriate package management update tools to get new versions of the package when they are released. When using the apt package to update the agent package, you will need to clear the configuration file modified prompt. This can be avoided using the --force-confold flag or by removing the modified configuration file before upgrading.

Once the configuration file has been populated, the following command will restart the agent so it can begin claiming:
```
sudo systemctl enable circleci-runner
sudo systemctl start circleci-runner
```

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