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

# Install the Runner

> Install the roboticks-runner Go binary v2 on Linux, macOS, or Windows. Register against a pool with one command. Verify with rbtk-runner doctor.

# Install the runner

`roboticks-runner` v2.x.x is a single static Go binary, **Cosign-signed**, published to [github.com/roboticks-io/roboticks-runner](https://github.com/roboticks-io/roboticks-runner) Releases. It runs on Linux, macOS, and Windows across amd64 and arm64.

## Prerequisites

<Check>Docker Engine 20.10+ (rootless or root) for sandboxed test execution.</Check>
<Check>Network reachability to `api.roboticks.io:443` and the S3 buckets returned by presigned-URL grants. Air-gapped pools talk only to your on-prem Roboticks platform.</Check>
<Check>A **pool registration token** minted from the dashboard or via `rbtk pool register-runner --pool <name>`.</Check>
<Check>If running simulators: a ROS2 distribution (Humble, Iron, or Rolling) and, for Gazebo Harmonic, NVIDIA driver 535+ on the host.</Check>

## Install

<Tabs>
  <Tab title="Linux / macOS (one-liner)">
    The install script detects OS and arch, downloads the matching binary, verifies the Cosign signature, and drops it at `/usr/local/bin/rbtk-runner`.

    ```bash theme={null}
    curl -fsSL https://get.roboticks.io/runner | bash
    ```

    Pin to a version:

    ```bash theme={null}
    curl -fsSL https://get.roboticks.io/runner | bash -s -- --version v2.3.1
    ```
  </Tab>

  <Tab title="Homebrew (macOS / Linux)">
    ```bash theme={null}
    brew install roboticks-io/tap/rbtk-runner
    ```

    Upgrade:

    ```bash theme={null}
    brew upgrade rbtk-runner
    ```
  </Tab>

  <Tab title="Chocolatey (Windows)">
    ```powershell theme={null}
    choco install rbtk-runner
    ```

    Or download the MSI installer from the [GitHub Releases](https://github.com/roboticks-io/roboticks-runner/releases) page and double-click it.
  </Tab>

  <Tab title="Direct download">
    Pick the asset for your platform from a release tag:

    ```bash theme={null}
    VERSION=v2.3.1
    OS=linux            # or darwin, windows
    ARCH=amd64          # or arm64

    curl -LO "https://github.com/roboticks-io/roboticks-runner/releases/download/${VERSION}/rbtk-runner-${OS}-${ARCH}"
    chmod +x rbtk-runner-${OS}-${ARCH}
    sudo mv rbtk-runner-${OS}-${ARCH} /usr/local/bin/rbtk-runner
    ```

    Verify the Cosign signature against the keyless transparency log:

    ```bash theme={null}
    cosign verify-blob \
      --certificate-identity "https://github.com/roboticks-io/roboticks-runner/.github/workflows/release.yml@refs/tags/${VERSION}" \
      --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
      --signature rbtk-runner-${OS}-${ARCH}.sig \
      rbtk-runner-${OS}-${ARCH}
    ```
  </Tab>
</Tabs>

## Verify the install

```bash theme={null}
rbtk-runner --version
# rbtk-runner v2.3.1 (commit abc1234, built 2026-04-12)
```

## Register against a pool

Generate a registration token in the dashboard (**Settings → Runner Pools → ⋯ → Generate token**) or via the CLI:

```bash theme={null}
rbtk pool register-runner --project warehouse --pool prod-gpu-farm
# Registration token: rbtk_pool_reg_xx... (valid 1 hour, single use)
```

On the runner machine:

```bash theme={null}
rbtk-runner register \
  --project warehouse \
  --pool prod-gpu-farm \
  --token rbtk_pool_reg_xx... \
  --name "gpu-host-04"
```

The runner exchanges the registration token for a long-lived **runner token** stored at `~/.roboticks/runner.yaml` (mode `0600`). The runner token rotates automatically on heartbeat.

<Warning>
  Registration tokens are **single-use** and expire 1 hour after minting. Generate a fresh one for each machine.
</Warning>

## Doctor check

`rbtk-runner doctor` runs a pre-flight on the host. It checks Docker, disk space, ROS2 install, GPU access, and connectivity to the platform.

```bash theme={null}
rbtk-runner doctor

✓ Docker 24.0.7 reachable
✓ Disk: 142 GB free at /var/lib/docker
✓ ROS2 humble found at /opt/ros/humble
✓ NVIDIA driver 535.183.01 — 1 × Tesla T4 (15109 MiB)
✓ Reaches api.roboticks.io (TLS, 32 ms RTT)
✓ Pool prod-gpu-farm — runner token valid, last heartbeat 8 s ago
```

Re-run with `--gpu` for deeper GPU diagnostics (CUDA version, nvidia-container-toolkit, sample container launch). See [GPU setup](/runners/gpu-setup).

## Start the runner

Foreground (good for first-time smoke test):

```bash theme={null}
rbtk-runner start
```

You should see a polling loop:

```
[15:02:11] heartbeat ok, 0 jobs in queue
[15:02:26] heartbeat ok, 1 job picked → job_8821 (pytest, ros:humble)
[15:02:54] job_8821 completed (28.3 s), uploading MCAP (12 MB) → S3
```

For production, install as a service — see [Run as a service](/runners/service).

## Next steps

<CardGroup cols={2}>
  <Card title="Configure capabilities" icon="gear" href="/runners/configuration">
    Declare ROS distros, simulators, GPU model, concurrency limits.
  </Card>

  <Card title="Manage pools" icon="layer-group" href="/runners/pool-management">
    Create, rotate, revoke. Per-pool job stats.
  </Card>

  <Card title="Run as a service" icon="rotate" href="/runners/service">
    systemd, launchd, Windows service. Drain-then-replace upgrades.
  </Card>

  <Card title="Troubleshooting" icon="bug" href="/runners/troubleshooting">
    Capability mismatch, MCAP upload failure, version skew.
  </Card>
</CardGroup>