Skip to main content

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.

​
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

​
Verify Installation

Check that the runner is installed correctly: 
roboticks-runner version
You should see output like: 
roboticks-runner v1.0.0

​
Get a Registration Token

Before registering your runner, you need a token from the Roboticks dashboard:
1

Navigate to Settings

Log in to Roboticks and go to Settings
2

Open Self-Hosted Runners

Click Fleet > Self-Hosted Runners
3

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

FlagDescriptionDefault
--tokenRegistration token (required)-
--nameDisplay name for the runnerhostname
--labelsLabels for job routing-
--max-jobsMaximum concurrent jobs (1-10)1
Example with options: 
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: 
roboticks-runner start
The runner will:
  1. Connect to the Roboticks API
  2. Send periodic heartbeats
  3. Poll for available jobs
  4. Execute jobs in Docker containers

​
Verify Connection

Check the runner status: 
roboticks-runner status
You can also verify in the dashboard:
  1. Go to Settings > Fleet > Self-Hosted Runners
  2. Your runner should show Online status

​
Troubleshooting

Ensure Docker is installed and running:
docker --version
docker info
If Docker is installed but not running:
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

Configuration

Customize runner settings

Run as Service

Set up automatic startup