# Getting Started with Runners

> Getting started guide for using Runners

## 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:

- [Hetzner](https://www.hetzner.com/)
- [Hostinger](https://www.hostinger.com/)
- [DigitalOcean](https://www.digitalocean.com/)
- [Linode](https://www.linode.com/)

## 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:

```bash
curl -fsSL https://bountyhub.org/runner/install.sh | sh
```

The script installs the runner to `$HOME/.local/bin` (or `/usr/local/bin` when
writable) and creates a `runner` shim.

### Agent runtime (dsh)

The installer also installs the pinned DeepSeek Harness payload under
`~/.bountyhub/dsh/versions/<version>` for
`runner-worker-local`/`runner-worker`, points `~/.bountyhub/dsh/current` at it,
verifies it against the release `SHA256SUMS`, and the runner finds it
automatically. Agent steps (`step.agent`) fail with an actionable error if no
harness is available; normal workflow steps are unaffected.

The runner resolves dsh in this order:

1. `BH_DSH_BIN`
2. `~/.bountyhub/dsh/current/bin/dsh` (versioned managed payload)
3. `~/.bountyhub/dsh/bin/dsh` (legacy flat payload)
4. `~/.bountyhub/dsh/node_modules/.bin/dsh` (older layout)
5. `/opt/bountyhub/dsh/bin/dsh` (container image)
6. `dsh` on `PATH` — used with a warning because it is not version-pinned by
BountyHub

To control the dsh version independently of the runner:

```bash
# Install dsh from a specific runner release (that release must ship dsh)
curl -fsSL https://bountyhub.org/runner/install.sh | \
  BOUNTYHUB_DSH_VERSION=vX.Y.Z sh

# Or install a locally built payload into the managed directory
scripts/release-dsh.sh --dsh-version 0.2.1-rc.2 --install
```

Skip the automatic payload with `BOUNTYHUB_RUNNER_DSH=0`, choose another root
with `BOUNTYHUB_DSH_DIR` (then set `BH_DSH_BIN`), or pin an explicit launcher
with `BH_DSH_BIN`. Use `BOUNTYHUB_DSH_SWITCH=0` to install a version without
moving `current`; switch later with:

```bash
ln -sfn versions/<version> ~/.bountyhub/dsh/current
```

Upgrades keep previous versions under `~/.bountyhub/dsh/versions`, so you can
roll back by moving `current`. The runner logs the payload's version and warns
if it differs from the version the runner was built against.

### Configuring the runner

To configure and register the runner, you should visit the
[New Runner](https://bountyhub.org/runners/new) 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
runner register --token "<TOKEN>" --url "https://bountyhub.org"
```

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
sudo -E runner service install --name "<your_runner_name>"
```

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
sudo -E runner service start --name <your_runner_name>
```

You can also stop and uninstall the service using:

```bash
sudo -E runner service stop --name "<your_runner_name>"
sudo -E runner service uninstall --name "<your_runner_name>"
```

### Running the runner manually

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

```bash
sudo -E runner run --name <your_runner_name>
```

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](https://hub.docker.com/repository/docker/bountyhuborg/runner/general).

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.

See [Custom Runner Images](/runners/custom-image) for a complete walkthrough,
including registering and running the container.

### Example Dockerfile

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

```Dockerfile
FROM ubuntu:24.04

USER root

COPY --from bountyhuborg/runner:latest /runner /usr/local/bin/runner
COPY --from bountyhuborg/runner:latest /bh /usr/local/bin/bh

WORDIR /root/workdir

RUN apt-get update && \
    apt-get install -y git curl wget build-essentiala golang && \
    rm -rf /var/lib/apt/lists/*

RUN go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest && \
    go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest && \
    go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
```

### Building the image

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

```bash
docker build -t bountyhub-runner:latest .
```

### Running the container

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

```bash
docker run bountyhub-runner:latest \
  -v "$(pwd):/root/.bountyhub/runners/my-runner" \
  runner configure --token "<TOKEN>" --url "https://bountyhub.org" --name "my-runner" --workdir "/root/workdir" --unattended
```

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

```bash
docker run -d --name bountyhub-runner \
  -v "$(pwd):/root/workdir" \
  bountyhub-runner:latest \
  runner run --name "my-runner" --workdir "/root/workdir"
```