Private Beta
.md

BountyHub Docs

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:

#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

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

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

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 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.

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

#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