Installation
Install roboticks-runner on your machine to start executing test jobs.
Prerequisites
Before installing, ensure you have:
Docker Engine installed and running
Network access to api.roboticks.io
A registration token from the Roboticks dashboard
Installation Methods
Homebrew (Recommended)
One-Liner
Direct Download
The easiest way to install on macOS and Linux:brew tap Roboticks-IO/tap
brew install roboticks-runner
brew upgrade roboticks-runner
Quick installation script that detects your platform:curl -fsSL https://get.roboticks.io/runner | bash
- Detects your OS and architecture
- Downloads the appropriate binary
- Installs to
/usr/local/bin
- Verifies the installation
Download the binary for your platform manually:Linux (amd64)curl -LO https://github.com/Roboticks-IO/roboticks-runner/releases/latest/download/roboticks-runner-linux-amd64
chmod +x roboticks-runner-linux-amd64
sudo mv roboticks-runner-linux-amd64 /usr/local/bin/roboticks-runner
curl -LO https://github.com/Roboticks-IO/roboticks-runner/releases/latest/download/roboticks-runner-linux-arm64
chmod +x roboticks-runner-linux-arm64
sudo mv roboticks-runner-linux-arm64 /usr/local/bin/roboticks-runner
curl -LO https://github.com/Roboticks-IO/roboticks-runner/releases/latest/download/roboticks-runner-darwin-arm64
chmod +x roboticks-runner-darwin-arm64
sudo mv roboticks-runner-darwin-arm64 /usr/local/bin/roboticks-runner
curl -LO https://github.com/Roboticks-IO/roboticks-runner/releases/latest/download/roboticks-runner-darwin-amd64
chmod +x roboticks-runner-darwin-amd64
sudo mv roboticks-runner-darwin-amd64 /usr/local/bin/roboticks-runner
Verify Installation
Check that the runner is installed correctly:
You should see output like:
Get a Registration Token
Before registering your runner, you need a token from the Roboticks dashboard:
Open Self-Hosted Runners
Click Fleet > Self-Hosted Runners
Add a Runner
Click Add Runner and copy the registration token
Registration tokens are single-use and expire after 24 hours. Generate a new one if yours has expired.
Register the Runner
Register your runner with the Roboticks platform:
roboticks-runner register --token <your-registration-token>
Registration Options
| Flag | Description | Default |
|---|
--token | Registration token (required) | - |
--name | Display name for the runner | hostname |
--labels | Labels for job routing | - |
--max-jobs | Maximum concurrent jobs (1-10) | 1 |
roboticks-runner register \
--token rbtk_reg_xxx \
--name "gpu-runner-01" \
--labels gpu,arm64 \
--max-jobs 4
Start the Runner
After registration, start the runner:
The runner will:
- Connect to the Roboticks API
- Send periodic heartbeats
- Poll for available jobs
- Execute jobs in Docker containers
Verify Connection
Check the runner status:
You can also verify in the dashboard:
- Go to Settings > Fleet > Self-Hosted Runners
- Your runner should show Online status
Troubleshooting
Ensure Docker is installed and running:docker --version
docker info
sudo systemctl start docker # Linux
open -a Docker # macOS
- Verify the token hasn’t expired (24-hour limit)
- Check network connectivity:
curl -I https://api.roboticks.io
- Ensure no firewall is blocking HTTPS traffic
Check the runner logs for errors:# If running in foreground
roboticks-runner start --log-level debug
# If running as service (Linux)
sudo journalctl -u roboticks-runner -f
Ensure the runner has permission to access Docker:# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in, or run:
newgrp docker
Next Steps
