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_endpointRoboticks API URL https://api.roboticks.iorunner_idUnique runner identifier Set during registration runner_tokenAuthentication token Set during registration nameDisplay name in dashboard hostname
Execution Settings Setting Description Default max_concurrent_jobsMaximum parallel jobs (1-10) 1work_dirDirectory for job files /tmp/roboticks
Timing Settings Setting Description Default poll_intervalHow often to check for jobs 30sheartbeat_intervalHow often to send heartbeat 30s
Logging Settings Setting Description Default log_levelVerbosity 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 < toke n > \ --labels gpu,arm64,production
In config file: labels : - gpu - arm64 - production
Common Label Examples Label Use Case gpuRunner has GPU available arm64ARM-based processor amd64x86-64 processor high-memoryRunner with 32GB+ RAM productionProduction environment access stagingStaging environment access internal-networkAccess 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.
Recommendations: 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_ENDPOINTOverride API endpoint ROBOTICKS_LOG_LEVELOverride log level ROBOTICKS_CONFIG_PATHCustom config file path
Example: 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
Run as Service Set up automatic startup
Troubleshooting Common issues and solutions
