Configuration
Customize your runner’s behavior through the configuration file or command-line flags.
Configuration File
Runner configuration is stored at ~/.roboticks/config.yaml. This file is created automatically during registration and can be modified afterward.
# API connection
api_endpoint: https://api.roboticks.io
# Runner identity (set during registration)
runner_id: runner_abc123
runner_token: rbtk_lrnr_xxx
# Display name shown in dashboard
name: my-runner
# Maximum parallel job execution (1-10)
max_concurrent_jobs: 2
# Labels for job routing
labels:
- gpu
- arm64
# Polling and heartbeat intervals
poll_interval: 30s
heartbeat_interval: 30s
# Logging level (debug, info, warn, error)
log_level: info
# Directory for job execution
work_dir: /tmp/roboticks
Configuration Options
Core Settings
| Setting | Description | Default |
|---|
api_endpoint | Roboticks API URL | https://api.roboticks.io |
runner_id | Unique runner identifier | Set during registration |
runner_token | Authentication token | Set during registration |
name | Display name in dashboard | hostname |
Execution Settings
| Setting | Description | Default |
|---|
max_concurrent_jobs | Maximum parallel jobs (1-10) | 1 |
work_dir | Directory for job files | /tmp/roboticks |
Timing Settings
| Setting | Description | Default |
|---|
poll_interval | How often to check for jobs | 30s |
heartbeat_interval | How often to send heartbeat | 30s |
Logging Settings
| Setting | Description | Default |
|---|
log_level | Verbosity level | info |
Labels
Labels allow you to route specific jobs to specific runners. Use labels to indicate runner capabilities like hardware features, network access, or environment type.
Setting Labels
During registration:
roboticks-runner register \
--token <token> \
--labels gpu,arm64,production
labels:
- gpu
- arm64
- production
Common Label Examples
| Label | Use Case |
|---|
gpu | Runner has GPU available |
arm64 | ARM-based processor |
amd64 | x86-64 processor |
high-memory | Runner with 32GB+ RAM |
production | Production environment access |
staging | Staging environment access |
internal-network | Access to internal resources |
Label Matching
Jobs can specify required labels. A runner will only receive jobs if it has all required labels:
- Job requires:
gpu, arm64
- Runner A labels:
gpu, arm64, production - matches
- Runner B labels:
gpu - does not match
Concurrency
The max_concurrent_jobs setting controls how many jobs can run simultaneously. Each job runs in its own Docker container.
Higher concurrency requires more system resources. Monitor CPU and memory usage to find the optimal setting for your machine.
| Machine Type | Recommended max_concurrent_jobs |
|---|
| 2 vCPU, 4GB RAM | 1-2 |
| 4 vCPU, 8GB RAM | 2-4 |
| 8 vCPU, 16GB RAM | 4-6 |
| 16+ vCPU, 32GB+ RAM | 6-10 |
Work Directory
The work_dir is where job files are downloaded and executed. Ensure:
- Sufficient disk space for artifacts
- Fast I/O (SSD recommended)
- Appropriate permissions
Custom work directory:
work_dir: /data/roboticks-jobs
Environment Variables
Some settings can be overridden via environment variables:
| Variable | Description |
|---|
ROBOTICKS_API_ENDPOINT | Override API endpoint |
ROBOTICKS_LOG_LEVEL | Override log level |
ROBOTICKS_CONFIG_PATH | Custom config file path |
ROBOTICKS_LOG_LEVEL=debug roboticks-runner start
Token Rotation
Runner tokens are automatically rotated for security. The runner handles this automatically:
- Heartbeat response may include a new token
- Runner updates its local configuration
- Subsequent requests use the new token
If your runner config file becomes corrupted or deleted, you’ll need to re-register the runner.
Viewing Current Configuration
Check the current configuration:
Output includes:
- Runner ID and name
- Current status
- Labels
- Concurrent job limit
- API endpoint
Updating Configuration
To change settings:
- Stop the runner (if running as a service)
- Edit
~/.roboticks/config.yaml
- Restart the runner
Do not modify runner_id or runner_token manually. These are managed by the registration process.
Next Steps
