> ## 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 pool > Reference for rbtk pool commands — list, create, register runners, inspect runners and stats, delete pools. # `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](/runners/pool-management). ## `rbtk pool list` ```bash theme={null} 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 ``` | Flag | Description | | -------------------------------- | ------------------- | | `--type self-hosted\|hosted` | Filter by pool type | | `--status ok\|degraded\|offline` | Filter by health | ## `rbtk pool create` ```bash theme={null} # 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 ` | Pool name; unique per project | | `--type self-hosted\|hosted` | Pool type (required) | | `--sku ` | Required for hosted; one of `hosted-ros2-cpu`, `hosted-gazebo-gpu`, `hosted-webots-cpu`, `hosted-webots-gpu` | | `--airgapped` | Mark pool air-gapped (project must also be air-gapped). See [Air-gapped mode](/runners/air-gapped). | | `--max-concurrent-jobs N` | Pool-level concurrency cap. Default: unlimited (subject to tier). | | `--tags k=v` | Repeatable. Pool tags for routing rules. | ## `rbtk pool register-runner` Mint a single-use, 1-hour registration token. Self-hosted only. ```bash theme={null} rbtk pool register-runner --pool prod-gpu-farm # Registration token: rbtk_pool_reg_xx... (valid 1h, single-use) ``` | Flag | Description | | ------------------ | ----------------------------------------------------------------------------- | | `--pool ` | Target pool (required) | | `--ttl ` | Token lifetime. Default `1h`. Max `24h` (Enterprise). | | `--uses ` | Multi-use token. Default `1`. Max `200` (Enterprise). Useful for autoscaling. | | `--output json` | Emit `{"token": "rbtk_pool_reg_..."}` for piping into `rbtk-runner register`. | ### Use it On the runner host: ```bash theme={null} 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. ```bash theme={null} 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. ```bash theme={null} 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. ```bash theme={null} 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: ```bash theme={null} 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. ```bash theme={null} 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` ```bash theme={null} 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 ``` | Flag | Description | | --------------- | ----------------------------------------------------------------------- | | `--pool ` | Target pool (required) | | `--confirm` | Skip the interactive confirm | | `--force` | Delete even with in-flight jobs (they're cancelled). **Use sparingly.** | ## Autoscaling pattern For ephemeral runners on a Kubernetes cluster or AWS Spot fleet: ```bash theme={null} # 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 The conceptual model. Get the Go binary onto a host.