Skip to main content

​
rbtk pool

The pool group lets you operate runner pools from the CLI. Most pool work happens once at setup time, then occasionally for tokens and capacity planning. 
rbtk pool
├── list                # List pools in the current project
├── create              # Create a new pool (self-hosted or hosted)
├── register-runner     # Mint a registration token for a self-hosted runner
├── runners             # List runners in a pool with status
├── stats               # Per-pool job throughput, queue wait, sim-minute usage
├── drain               # Stop accepting new jobs (graceful shutdown helper)
├── runner-revoke       # Invalidate one runner's token
└── delete              # Delete an empty pool
For the pool model itself see Runners → Pool management.

​
rbtk pool list

rbtk pool list

NAME                TYPE         SKU                 RUNNERS   STATUS    JOBS 24h
prod-gpu-farm       self-hosted  —                   4 online  OK        412
staging-gpu         self-hosted  —                   1 online  OK        87
fallback-gazebo     hosted       hosted-gazebo-gpu   —         OK        14
fallback-cpu        hosted       hosted-ros2-cpu     —         OK        211
FlagDescription
--type self-hosted|hostedFilter by pool type
--status ok|degraded|offlineFilter by health

​
rbtk pool create

# Self-hosted
rbtk pool create --name prod-gpu-farm --type self-hosted

# Hosted (Roboticks-operated)
rbtk pool create --name fallback-gazebo --type hosted --sku hosted-gazebo-gpu
FlagDescription
--name <name>Pool name; unique per project
--type self-hosted|hostedPool type (required)
--sku <sku>Required for hosted; one of hosted-ros2-cpu, hosted-gazebo-gpu, hosted-webots-cpu, hosted-webots-gpu
--airgappedMark pool air-gapped (project must also be air-gapped). See Air-gapped mode.
--max-concurrent-jobs NPool-level concurrency cap. Default: unlimited (subject to tier).
--tags k=vRepeatable. Pool tags for routing rules.

​
rbtk pool register-runner

Mint a single-use, 1-hour registration token. Self-hosted only. 
rbtk pool register-runner --pool prod-gpu-farm
# Registration token: rbtk_pool_reg_xx... (valid 1h, single-use)
FlagDescription
--pool <name>Target pool (required)
--ttl <duration>Token lifetime. Default 1h. Max 24h (Enterprise).
--uses <N>Multi-use token. Default 1. Max 200 (Enterprise). Useful for autoscaling.
--output jsonEmit {"token": "rbtk_pool_reg_..."} for piping into rbtk-runner register.

​
Use it

On the runner host: 
TOKEN=$(rbtk pool register-runner --pool prod-gpu-farm --output json | jq -r .token)
rbtk-runner register --pool prod-gpu-farm --token $TOKEN --name $(hostname)

​
rbtk pool runners

List runners in a pool with their status, capabilities, and concurrency. 
rbtk pool runners --pool prod-gpu-farm
rbtk pool runners --pool prod-gpu-farm --watch    # auto-refresh every 5s

NAME           STATUS    JOBS      CAPABILITIES                          LAST HEARTBEAT
gpu-host-01    ONLINE    1/4       ros:humble,iron · sim:gazebo · gpu:T4 6s ago
gpu-host-02    ONLINE    3/4       ros:humble,iron · sim:gazebo · gpu:T4 9s ago
gpu-host-03    DRAINING  2/4       ros:humble       · sim:gazebo · gpu:T4 11s ago
gpu-host-04    OFFLINE   0/0       (last seen 2h ago)                    —
--output json returns the full record including declared CUDA version, work-dir disk usage, and runner-version.

​
rbtk pool stats

Throughput, queue wait, and (for hosted pools) sim-minute usage. 
rbtk pool stats --pool prod-gpu-farm --since 24h
rbtk pool stats --pool fallback-gazebo --since 30d --output json

POOL               prod-gpu-farm (self-hosted, project: warehouse)
WINDOW             last 24h
JOBS               412 dispatched · 408 completed · 3 failed · 1 requeued
WALL TIME          17h 24m total · avg 152s
QUEUE WAIT         p50 1.2s · p95 7.4s · p99 22.1s
TOP REQUIREMENTS   ros:humble (231) · gazebo-harmonic (164) · gpu (164)
Hosted pools additionally show: 
BILLED SIM MINUTES 1043 min (of 500 included → 543 min metered at $0.10/min = $54.30)

​
rbtk pool drain

Stop all runners in the pool from accepting new jobs. In-flight jobs run to completion. Useful before a coordinated upgrade. 
rbtk pool drain --pool prod-gpu-farm
# All 4 runners in prod-gpu-farm marked DRAINING.
# In-flight jobs: 5 — watch with: rbtk pool runners --pool prod-gpu-farm --watch
Reverse: 
rbtk pool resume --pool prod-gpu-farm

​
rbtk pool runner-revoke

Invalidate one runner’s token without touching the others. Use this if a host is compromised. 
rbtk pool runner-revoke --pool prod-gpu-farm --runner gpu-host-04
The runner’s next heartbeat returns 401; it exits and the host must re-register. Any in-flight job on that runner is failed and requeued.

​
rbtk pool delete

rbtk pool delete --pool old-staging-gpu
# Refused: pool has 1 ONLINE runner. Drain first.

rbtk pool drain --pool old-staging-gpu
# Wait for runners to go OFFLINE...
rbtk pool delete --pool old-staging-gpu --confirm
FlagDescription
--pool <name>Target pool (required)
--confirmSkip the interactive confirm
--forceDelete even with in-flight jobs (they’re cancelled). Use sparingly.

​
Autoscaling pattern

For ephemeral runners on a Kubernetes cluster or AWS Spot fleet: 
# Mint a long-lived multi-use token (Enterprise tier)
rbtk pool register-runner --pool prod-gpu-farm --ttl 24h --uses 50 \
  --output json | jq -r .token > /etc/roboticks/pool-token

# On each pod / instance startup:
rbtk-runner register --pool prod-gpu-farm \
  --token "$(cat /etc/roboticks/pool-token)" \
  --name "${HOSTNAME}-${POD_UID}"

# On shutdown:
rbtk-runner drain --timeout 110s
The runner cleans up its registration after a successful drain.

​
Next

Runner Pools overview

The conceptual model.

Install a runner

Get the Go binary onto a host.