# Getting Started with Runners

This guide will help you get started effectively using runners. You can run everything on your own machine.

However, you should set up a VPS in order to have your runners available 24/7.

There are many platforms to choose from, such as:

# Running runners on the host machine

Running runners on your host machine is the easiest way to get started.

# Prerequisites

  • Linux (x86_64) operating system.
  • Tools installed on your machine, accessible using PATH

# Installing the runner

To install the runner, run the following command in your terminal:

bash

You can also use curl:

bash

The script will install the runner on your machine on path: $HOME/.local/bin

You should probably have this path in your PATH environment variable.

# Configuring the runner

To configure and register the runner, you should visit the New Runner page.

New one-time-token will be generated for you to register your runner.

You can simply copy the command shown on that page and run it on your terminal. The command looks like following:

bash

You can also set the name and the workdir using flags. Important thing to note is that --unattended flags use flag value and/or default values without asking for confirmation.

By default, the runner is named as your hostname, and the workdir is set to $HOME/.bountyhub/runner/<runner_name>.

# Running as the service

If you are configuring the runner to run 24/7, you should run it as a service.

Few important things to note before running as a service:

  1. To install the service, you either must be running as root user, or have sudo privileges.
  2. The service is systemd based, so your system must be using systemd as init system.
  3. If you are not running as root, you should check the environment variables If you are running as a normal user, using sudo command to elevate privileges so you can install the service, make sure you run sudo -E to preserve the environment variables. That way, there are no surprises when the service is started.

The runner knows how to install itself as a service. To do so, you can run:

bash

The --name flag is optional. If you used the default name, you don't need to provide it.

Otherwise, the name is important since you can have multiple runners running as a service on your machine.

After installing the service, you can start it using:

bash

You can also stop and uninstall the service using:

bash

# Running the runner manually

If you want to run the runner in the foreground (testing locally), you can simply run:

bash

This will start the runner in the foreground, and you will see the logs in your terminal.

# Running runner using docker

As part of the runner release, the docker image is also published to Docker Hub. The image can be found on Docker Hub, and this
Dockerfile is used to build the image.

As you can see, the runner image is only shipping the runner and bh CLI binaries. It is designed this way so you can build your own custom image, while using officially provided image as a base. That way, you can copy the binaries, while being able to install tools you need.

Otherwise, all tools would have to be included inside the image, while still not solving the issue of you being able to run proprietary tools.

# Example Dockerfile

Here is an example Dockerfile that uses the official runner image as a base, and instal some tools.

Dockerfile

# Building the image

To build the image, you can run the following command in the directory where your Dockerfile is located:

bash

# Running the container

To run the container, you first need to generate the config file used to store credentials.

bash

After generating the config file, you can run the container using the following command:

bash