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.
rbtk poolThe 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 listNAME 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
Flag Description --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
Flag Description --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-runnerMint 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)
Flag Description --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 runnersList 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 statsThroughput, 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 drainStop 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-revokeInvalidate 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 deleterbtk 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
Flag Description --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.
