---
title: "Migrate from launch agent to machine runner 3 on Linux"
description: "Migrate an existing launch agent installation on Linux to machine runner 3. Uninstall launch agent, then install the machine runner 3 agent."
platform: "Cloud, Server"
doc_version: "unversioned"
last_updated: "2026-10-14"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# Migrate from launch agent to machine runner 3 on Linux

This page describes how to migrate an existing launch agent installation to machine runner 3. Machine runner 3 includes improved network resiliency, and a simpler installation management strategy, utilizing operating system packages.

Migrating from launch agent to machine runner 3 is a straightforward process. The prerequisites remain the same. First, uninstall and remove launch agent, then install the machine runner 3 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.

1.  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 installs a new service unit:
    
    ```shell
    sudo systemctl stop circleci.service
    sudo systemctl disable circleci.service
    
    sudo rm /usr/lib/systemd/system/circleci.service
    ```
    
2.  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.
    
3.  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:
    
    ```shell
    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, uninstall the SELinux policy using the following command:

```shell
sudo semodule -r circleci_launch_agent
```

## 2\. Install the machine agent

1.  Follow the instructions provided in [Install Machine Runner 3 on Linux](https://circleci.com/docs/runner/install-machine-runner-3-on-linux/) to install machine runner 3 using the provided packages.
    
2.  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, 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 modified configuration file 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:
    
    ```shell
    sudo systemctl enable circleci-runner
    sudo systemctl start circleci-runner
    ```
    

## Additional resources

*   [Machine Runner 3 Configuration Reference](https://circleci.com/docs/runner/machine-runner-3-configuration-reference/)
    
*   [Machine Runner 3 Manual Installation Reference](https://circleci.com/docs/runner/machine-runner-3-manual-installation/)