> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bentralabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install a runner

Runners execute your workflows in your own infrastructure: a Kubernetes cluster, a Docker host or a Linux VM. They connect **out** to Bentra over HTTPS and poll for jobs. Nothing connects in to them. See [Network requirements](https://docs.bentralabs.com/runners/network.md).

## 1. Create a pool and a token

In Bentra, open **Settings → Runner Pools** and create a pool (or use the default one). The pool page shows a runner token once, right after you create it. Copy it then: Bentra keeps only a hash.

Workflows choose a pool in **Settings → Execution**. Runs without a pool go to the default pool.

## 2. Install

The pool page shows these commands with your host and token filled in.

**Kubernetes (Helm)**

Requires Helm 3+.

```bash theme={"theme":{"light":"github-light","dark":"night-owl"}}
helm install bentra-runner oci://ghcr.io/bentrallc/charts/bentra-runner \
  --version <version> \
  --set runner.token="<your-runner-token>" \
  --set runner.controlPlane="https://<your-bentra-host>" \
  --set deployment.replicas=1 \
  --namespace bentra-runners \
  --create-namespace
```

* Raise `deployment.replicas` to run more always-on runners.
* To autoscale with KEDA v2+, use `--set deployment.enabled=false --set keda.enabled=true --set keda.maxReplicas=10` instead.
* Pin `image.tag` to the same version as the chart when you upgrade:

  ```bash theme={"theme":{"light":"github-light","dark":"night-owl"}}
  helm upgrade bentra-runner oci://ghcr.io/bentrallc/charts/bentra-runner \
    --version <version> --reuse-values --set image.tag=<version>
  ```

**Linux VM**

```bash theme={"theme":{"light":"github-light","dark":"night-owl"}}
curl -fsSL https://raw.githubusercontent.com/bentraLLC/bentra-runners/v<version>/runners/install.sh \
  | sudo bash -s -- --token "<your-runner-token>" --url "https://<your-bentra-host>"
```

The script installs a systemd service. Check that it's running with `systemctl status bentra-runner`. Pass `--instance <name>` to run several runners on one VM.

**Docker**

The pool page has the full commands: a network, the orchestrator container and the runner image it starts.

## 3. Check it connected

The pool page lists the connected runners with their version and status, refreshed every 15 seconds. A runner older than the latest release shows **Outdated**.

## Plan limits

Your plan sets how many runners can be connected at once, across all your pools together, and how many runner pools you can create. See [Plans and limits](https://docs.bentralabs.com/plans.md).

| | Free | Team | Business | Enterprise |
| - | - | - | - | - |
| Runners (all pools together) | 1 | 3 | 10 | Unlimited |
| Runner pools | 1 | 1 | 2 | Unlimited |

* **Settings → Runner Pools** shows meters for active runners and runner pools.
* A runner that starts when you're at the limit is refused jobs and keeps retrying. It gets a slot about 90 seconds after another runner stops.
* At the pool limit, you can't create another pool. Existing pools keep working if your plan changes.
* On Team and Business, Bentra can add extra runners or pools to your account. See [Billing](https://docs.bentralabs.com/guides/billing.md#extra-runners-and-runner-pools).

## Versions

* Runners send their version with every call.
* Bentra has a minimum supported runner version. Below it, every runner call is refused with **426 Upgrade Required**, and the response includes the minimum and the latest versions. Above the minimum, older runners keep working and show as Outdated.
* Breaking changes to the runner protocol are listed in the runner changelog. They raise the minimum version.
* Upgrade runners to the latest release when you see **Outdated**: Helm `upgrade`, rerun the VM install script with the new version, or pull the new image.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.