Configuration

Runner state lives in ~/.roboticks/runner.yaml (or %APPDATA%\roboticks\runner.yaml on Windows). The file is created by rbtk-runner register and updated automatically on token rotation. You edit the capabilities and resource stanzas.

File layout

# Auto-managed by rbtk-runner; do not edit
runner_id: rnr_8d2f...
runner_token: rbtk_rnr_xx...
api_endpoint: https://api.roboticks.io
pool: prod-gpu-farm
project: warehouse

# You own everything below

name: gpu-host-04
log_level: info              # debug | info | warn | error

capabilities:
  ros_distros: [humble, iron]
  sim_engines: [gazebo-harmonic, webots]
  gpu:
    enabled: true
    count: 1
    model: "Tesla T4"
    cuda: "12.4"
  labels: [self-hosted, gpu, prod]

resources:
  max_concurrent_jobs: 3
  job_timeout: 30m
  work_dir: /var/lib/roboticks/work
  cpu_limit: 0                # 0 = no cap; otherwise vCPUs
  memory_limit_mb: 0          # 0 = no cap

network:
  airgapped: false            # set true for air-gapped pools

heartbeat_interval: 15s
poll_interval: 5s

Capabilities

Capabilities are matched all-or-nothing against the job requirements declared in the test job’s payload. A runner missing a required capability is silently skipped — it never sees the job.

ROS2 distros

capabilities:
  ros_distros: [humble, iron, rolling]

The runner mounts the matching /opt/ros/{distro} into the test container. List only the distros actually installed on the host; rbtk-runner doctor flags drift.

Sim engines

capabilities:
  sim_engines: [gazebo-harmonic, webots]

Value	Engine	GPU required?
`gazebo-harmonic`	Gazebo Harmonic (recommended)	Strongly recommended
`gazebo-classic`	Gazebo Classic 11 (deprecated upstream)	Optional
`webots`	Webots R2024a+	GPU optional
`ignition`	Legacy alias for Gazebo Harmonic	Same as Harmonic

GPU

capabilities:
  gpu:
    enabled: true
    count: 2
    model: "Tesla T4"
    cuda: "12.4"

Jobs that need a GPU set requires_gpu: true in the payload. If model is also set on the job, the runner is matched only if its declared model contains the substring. See GPU setup for nvidia-container-toolkit configuration.

Labels

Arbitrary string tags. Jobs may request a label (e.g., ldra-licensed) — runners without it are skipped.

capabilities:
  labels: [self-hosted, ldra-licensed, prod-network]

Resources

Field	Default	Notes
`max_concurrent_jobs`	1	How many jobs run in parallel. Each spawns one Docker container.
`job_timeout`	30m	Hard kill if a job exceeds this.
`work_dir`	`/var/lib/roboticks/work`	Scratch for git checkouts, build artifacts, MCAP files before upload.
`cpu_limit`	0	Per-job vCPU cap (Docker `--cpus`). 0 = unlimited.
`memory_limit_mb`	0	Per-job memory cap (Docker `--memory`). 0 = unlimited.

Pick max_concurrent_jobs based on host capacity:

Host class	Suggested `max_concurrent_jobs`
4 vCPU / 8 GB, CPU tests only	2
8 vCPU / 16 GB, mixed	4
16 vCPU / 32 GB + 1× T4 GPU	4 (GPU is the bottleneck)
32 vCPU / 64 GB + 4× T4	8–12

Log level

log_level: debug

debug includes every HTTP request to the platform and the full Docker run command. Use it when diagnosing capability mismatches or upload failures. Per-invocation override:

ROBOTICKS_LOG_LEVEL=debug rbtk-runner start

Environment variables

Variable	Overrides
`ROBOTICKS_API_ENDPOINT`	`api_endpoint`
`ROBOTICKS_LOG_LEVEL`	`log_level`
`ROBOTICKS_RUNNER_CONFIG`	path to a different config file
`ROBOTICKS_WORK_DIR`	`resources.work_dir`
`ROBOTICKS_MAX_JOBS`	`resources.max_concurrent_jobs`

Validate a config

rbtk-runner config validate
# ✓ runner.yaml is valid
# ✓ Capabilities can be served by this host (rbtk-runner doctor for details)

Hot reload

The runner watches runner.yaml and re-applies capability changes on the next poll without restarting. Resource limits and log_level require a restart.

Token rotation

On every heartbeat the platform may return a fresh runner_token. The runner writes the new token to runner.yaml atomically. Never copy runner.yaml between machines — each runner identity is bound to its host.

If runner.yaml is lost or corrupted, run rbtk-runner register again with a fresh registration token. The old runner identity will be reaped after 24 hours of missed heartbeats.

Inspect current state

rbtk-runner status

Runner       gpu-host-04 (rnr_8d2f4a91)
Pool         prod-gpu-farm (project: warehouse)
Status       ONLINE — last heartbeat 4 s ago
Jobs         2 running / 3 max
Capabilities ros: humble,iron · sim: gazebo-harmonic · gpu: 1× Tesla T4
Uptime       3d 7h
Version      v2.3.1

Quick Start

GitHub App

Requirements

Traceability

Testing

SDK

Self-Hosted Runners

AI Features

CLI

Evidence Packs

Standards Coverage

Compliance Patterns

Integrations

Pricing

Resources

Runner Configuration

Configuration

File layout

Capabilities

ROS2 distros

Sim engines

GPU

Labels

Resources

Log level

Environment variables

Validate a config

Hot reload

Token rotation

Inspect current state

Next steps

Run as a service

GPU setup

​Configuration

​File layout

​Capabilities

​ROS2 distros

​Sim engines

​GPU

​Labels

​Resources

​Log level

​Environment variables

​Validate a config

​Hot reload

​Token rotation

​Inspect current state

​Next steps

Run as a service

GPU setup

Configuration

File layout

Capabilities

ROS2 distros

Sim engines

GPU

Labels

Resources

Log level

Environment variables

Validate a config

Hot reload

Token rotation

Inspect current state

Next steps