Runner setup

This section describes the best practices how to configure and run the runner from the system that doesn't have the runner installed. It is worth re-iterating that the runner is only available for Linux.

Setup example

This setup assumes that you have a Linux machine, and you have terminal access to it. It can be your local machine, or it can be a VPS.

Step 1: Downloading assets

To install the runner, we need to download the binary. The instructions how to download the runner are available in the New runner page.

You can see the dropdown containing runner versions. Please always pick the latest version. The platform is heavily under development, and the new features will be available on the newest runner only.

If you are running on the VPS, you have the example bash script to download the runner assets using wget command, and to unzip it.

If you want to run the runner on your local machine where you have GUI, you can click the download button instead.

Once your runner assets are downloaded and extracted, you can proceed to the next step.

Step 2: Configuring the runner

Copy the command from the UI. The token provided by the page is a single-use token valid for 15 minutes. That means that you cannot re-use the same token to configure your runners multiple times.

Once the command is executed, the runner will prompt you for the name. Please assign the unique name to the runner.

If you don't want to have a prompt, you can provide the name using the --name flag.

If configuration is successful, you can see that in your current working directory, there is a new file named .runner. Please do not share this file with anyone. The file contains configuration information for the runner to use when restarted. If you remove this file, the runner will not be able to connect to the bountyhub back-end, and you will have to re-configure it.

Step 3: Run the runner

In order to start the runner, you can run it as a service (in the background), or you can run it as long as your terminal session is open (foreground). Regardless of the method, you may want to step back at this moment and set up your machine.

Before running the runner, make sure the environment contains proper PATH, BOUNTYHUB_TOKEN, and other environment variables.

Common issue is to run sudo ./runner service install and then sudo ./runner service start. This leaves a false impression that the runner will have access to the same environment variables as the user who installed the runner. This is not the case. The runner will have access to the environment variables that are available in /etc/environment. To see what environment variables are available to the root user, you can run sudo env.

Common checklist of things to do before running the runner:

• Make sure you understand the environment variables that are available to the runner. If you are running the runner as a service, you can run sudo env to see what is available. Otherwise, you can run env to see what is available to the current user.
• Make sure that all tools are present on the PATH.
• If you are using the bh CLI, make sure that the BOUNTYHUB_TOKEN is present in the environment.
• Make sure that the runner has access to the internet. If you are behind the proxy, make sure that the proxy is configured.