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

# Runner Configuration

> The runner config file format. Declare ROS distros, simulation engines, GPU model, max concurrent jobs, resource limits, and log level.

# 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

```yaml theme={null}
# 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

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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](/runners/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.

```yaml theme={null}
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

```yaml theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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.

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

## Inspect current state

```bash theme={null}
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
```

## Next steps

<CardGroup cols={2}>
  <Card title="Run as a service" icon="rotate" href="/runners/service">
    systemd, launchd, Windows. Drain-then-replace updates.
  </Card>

  <Card title="GPU setup" icon="microchip" href="/runners/gpu-setup">
    nvidia-container-toolkit, multi-GPU pools.
  </Card>
</CardGroup>