Skip to main content

​
Install the runner

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

​
Prerequisites

Docker Engine 20.10+ (rootless or root) for sandboxed test execution.
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.
A pool registration token minted from the dashboard or via rbtk pool register-runner --pool <name>.
If running simulators: a ROS2 distribution (Humble, Iron, or Rolling) and, for Gazebo Harmonic, NVIDIA driver 535+ on the host.

​
Install

The install script detects OS and arch, downloads the matching binary, verifies the Cosign signature, and drops it at /usr/local/bin/rbtk-runner.
curl -fsSL https://get.roboticks.io/runner | bash
Pin to a version:
curl -fsSL https://get.roboticks.io/runner | bash -s -- --version v2.3.1

​
Verify the install

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: 
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: 
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.
Registration tokens are single-use and expire 1 hour after minting. Generate a fresh one for each machine.

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

​
Start the runner

Foreground (good for first-time smoke test): 
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.

​
Next steps

Configure capabilities

Declare ROS distros, simulators, GPU model, concurrency limits.

Manage pools

Create, rotate, revoke. Per-pool job stats.

Run as a service

systemd, launchd, Windows service. Drain-then-replace upgrades.

Troubleshooting

Capability mismatch, MCAP upload failure, version skew.