# Install CircleCI machine runner on AWS Graviton

## In this learning path

- [Introduction](https://learn.arm.com/learning-paths/servers-and-cloud-computing/circleci-on-aws/)
- [Get Started with CircleCI on AWS Graviton](https://learn.arm.com/learning-paths/servers-and-cloud-computing/circleci-on-aws/background/)
- [Create an AWS EC2 Arm64 Graviton Instance](https://learn.arm.com/learning-paths/servers-and-cloud-computing/circleci-on-aws/instance/)
- [Install CircleCI CLI](https://learn.arm.com/learning-paths/servers-and-cloud-computing/circleci-on-aws/circlecli-installation/)
- [Create a resource class in CircleCI](https://learn.arm.com/learning-paths/servers-and-cloud-computing/circleci-on-aws/resource-class/)
- [Install CircleCI machine runner on AWS Graviton](https://learn.arm.com/learning-paths/servers-and-cloud-computing/circleci-on-aws/circleci-runner-installation/)
- [Verify CircleCI Arm64 Self-Hosted runner](https://learn.arm.com/learning-paths/servers-and-cloud-computing/circleci-on-aws/validation/)
- [Next Steps](https://learn.arm.com/learning-paths/servers-and-cloud-computing/circleci-on-aws/_next-steps/)

This section provides step-by-step instructions to install and configure the CircleCI Machine Runner. With this setup, your self-hosted Arm64 environment can efficiently execute CircleCI jobs directly on the Graviton architecture, enabling faster builds and improved performance for ARM-based workloads.

## Add the CircleCI package repository

For Debian/Ubuntu-based systems running on AWS Graviton (Arm64), first add the official CircleCI repository. This ensures you can install the CircleCI Runner package directly using `apt`.

```bash
curl -s https://packagecloud.io/install/repositories/circleci/runner/script.deb.sh?any=true | sudo bash
```

After successful execution, the CircleCI repository will be added under `/etc/apt/sources.list.d/`. Run the command to verify:

```bash
ls /etc/apt/sources.list.d/
```

## Install the CircleCI runner

To install the CircleCI runner, use the following command:

```bash
sudo apt-get install -y circleci-runner
```

This command installs the latest CircleCI Machine Runner for your Arm64 system. The runner program is placed in `/usr/bin/`, and its configuration files are stored in `/etc/circleci-runner/`.

## Configure the runner authentication token

Update the CircleCI runner configuration with your authentication token. This token is generated from the resource class you created in the CircleCI Dashboard.

```bash
export RUNNER_AUTH_TOKEN="YOUR_AUTH_TOKEN"
sudo sed -i "s/<< AUTH_TOKEN >>/$RUNNER_AUTH_TOKEN/g" /etc/circleci-runner/circleci-runner-config.yaml
```

## Enable and start the CircleCI runner

Set the CircleCI runner service to start automatically and verify it is running:

```bash
sudo systemctl enable circleci-runner
sudo systemctl start circleci-runner
sudo systemctl status circleci-runner
```

If the status shows active (running), your runner is successfully installed and connected to CircleCI.

```plaintext
● circleci-runner.service - Run the CircleCI self-hosted runner agent
     Loaded: loaded (/usr/lib/systemd/system/circleci-runner.service; enabled; preset: enabled)
     Active: active (running) since Fri 2025-10-17 05:33:20 UTC; 51min ago
   Main PID: 2226 (circleci-runner)
      Tasks: 9 (limit: 18717)
     Memory: 53.0M (peak: 66.9M)
        CPU: 1.249s
     CGroup: /system.slice/circleci-runner.service
             └─2226 /usr/bin/circleci-runner machine -c /etc/circleci-runner/circleci-runner-config.yaml
```

This confirms that the CircleCI Runner is actively connected to your CircleCI account and ready to accept jobs.

You can also verify it from the dashboard:

![Self-Hosted Runners](https://www.arm.com/developer-hub/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/runner.png)  
*Self-Hosted Runners*