Skip to main content

​
Running as a Service

Configure roboticks-runner to start automatically and run in the background.

​
Why Run as a Service?

Running the runner as a system service provides:
  • Automatic startup on system boot
  • Automatic restart if the runner crashes
  • Background execution without a terminal session
  • System logging integration

​
Linux (systemd)

Most modern Linux distributions use systemd for service management.

​
Create Service File

Create a systemd service file: 
sudo tee /etc/systemd/system/roboticks-runner.service << 'EOF'
[Unit]
Description=Roboticks Runner
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=roboticks
ExecStart=/usr/local/bin/roboticks-runner start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF
For better security, run the service as a dedicated user: 
# Create user
sudo useradd -r -s /bin/false roboticks

# Add to docker group
sudo usermod -aG docker roboticks

# Copy configuration
sudo mkdir -p /home/roboticks/.roboticks
sudo cp ~/.roboticks/config.yaml /home/roboticks/.roboticks/
sudo chown -R roboticks:roboticks /home/roboticks/.roboticks
If you prefer to run as your own user, change User=roboticks to User=<your-username> in the service file.

​
Enable and Start

# Reload systemd configuration
sudo systemctl daemon-reload

# Enable auto-start on boot
sudo systemctl enable roboticks-runner

# Start the service
sudo systemctl start roboticks-runner

​
Manage the Service

# Check status
sudo systemctl status roboticks-runner

# View logs
sudo journalctl -u roboticks-runner -f

# Stop the service
sudo systemctl stop roboticks-runner

# Restart the service
sudo systemctl restart roboticks-runner

# Disable auto-start
sudo systemctl disable roboticks-runner

​
macOS (launchd)

macOS uses launchd for service management.

​
Create Launch Agent

Create a plist file for your user: 
cat > ~/Library/LaunchAgents/io.roboticks.runner.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>io.roboticks.runner</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/roboticks-runner</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/roboticks-runner.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/roboticks-runner.err</string>
</dict>
</plist>
EOF

​
Load the Service

# Load and start
launchctl load ~/Library/LaunchAgents/io.roboticks.runner.plist

# Verify it's running
launchctl list | grep roboticks

​
Manage the Service

# Stop the service
launchctl unload ~/Library/LaunchAgents/io.roboticks.runner.plist

# Restart (unload then load)
launchctl unload ~/Library/LaunchAgents/io.roboticks.runner.plist
launchctl load ~/Library/LaunchAgents/io.roboticks.runner.plist

# View logs
tail -f /tmp/roboticks-runner.log

​
Windows

On Windows, you can use the built-in Service Manager or NSSM (Non-Sucking Service Manager).

​
Using NSSM

  1. Download NSSM from https://nssm.cc/
  2. Install the service:
nssm install roboticks-runner "C:\path\to\roboticks-runner.exe" start
nssm set roboticks-runner AppDirectory "C:\path\to\config"
nssm set roboticks-runner DisplayName "Roboticks Runner"
nssm set roboticks-runner Description "Self-hosted test runner for Roboticks"
nssm set roboticks-runner Start SERVICE_AUTO_START
nssm start roboticks-runner

​
Manage the Service

# Check status
nssm status roboticks-runner

# Stop
nssm stop roboticks-runner

# Start
nssm start roboticks-runner

# Remove
nssm remove roboticks-runner confirm

​
Docker Compose

Alternatively, run the runner itself in a Docker container: 
version: '3.8'
services:
  roboticks-runner:
    image: roboticks/runner:latest
    restart: always
    volumes:
      - ~/.roboticks:/root/.roboticks:ro
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - ROBOTICKS_LOG_LEVEL=info
Running the runner in Docker requires mounting the Docker socket, which gives the container access to the host’s Docker daemon.

​
Verifying Service Status

After setting up the service, verify it’s working:
  1. Check service status using the commands above
  2. Check dashboard: Runner should show Online in Settings > Fleet > Self-Hosted Runners
  3. Test a job: Run a test job to verify end-to-end functionality

​
Troubleshooting

Check the logs for errors:
# Linux
sudo journalctl -u roboticks-runner -n 50

# macOS
cat /tmp/roboticks-runner.err
Common issues:
  • Docker not running
  • Config file not found or invalid
  • Insufficient permissions
  • Verify network connectivity to api.roboticks.io
  • Check if the runner token has expired
  • Ensure the config file is readable by the service user
Ensure the service user:
  • Is in the docker group
  • Has read access to the config file
  • Has write access to the work directory
Check logs for the restart reason. Common causes:
  • Out of memory (reduce max_concurrent_jobs)
  • Network connectivity issues
  • Docker daemon problems

​
Next Steps

Configuration

Customize runner settings

CI/CD Integration

Use runners in pipelines