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

Create Service User (Recommended)

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

Download NSSM from https://nssm.cc/
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:

Check service status using the commands above
Check dashboard: Runner should show Online in Settings > Fleet > Self-Hosted Runners
Test a job: Run a test job to verify end-to-end functionality

Troubleshooting

Service fails to start

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

Service starts but runner is Offline

Verify network connectivity to api.roboticks.io
Check if the runner token has expired
Ensure the config file is readable by the service user

Permission denied errors

Ensure the service user:

Is in the docker group
Has read access to the config file
Has write access to the work directory

Service restarts frequently

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

Quick Start

GitHub App

Requirements

Traceability

Testing

SDK

Self-Hosted Runners

AI Features

CLI

Evidence Packs

Standards Coverage

Compliance Patterns

Integrations

Pricing

Resources

Running as a Service

Running as a Service

Why Run as a Service?

Linux (systemd)

Create Service File

Create Service User (Recommended)

Enable and Start

Manage the Service

macOS (launchd)

Create Launch Agent

Load the Service

Manage the Service

Windows

Using NSSM

Manage the Service

Docker Compose

Verifying Service Status

Troubleshooting

Next Steps

Configuration

CI/CD Integration

​Running as a Service

​Why Run as a Service?

​Linux (systemd)

​Create Service File

​Create Service User (Recommended)

​Enable and Start

​Manage the Service

​macOS (launchd)

​Create Launch Agent

​Load the Service

​Manage the Service

​Windows

​Using NSSM

​Manage the Service

​Docker Compose

​Verifying Service Status

​Troubleshooting

​Next Steps

Configuration

CI/CD Integration

Running as a Service

Why Run as a Service?

Linux (systemd)

Create Service File

Create Service User (Recommended)

Enable and Start

Manage the Service

macOS (launchd)

Create Launch Agent

Load the Service

Manage the Service

Windows

Using NSSM

Manage the Service

Docker Compose

Verifying Service Status

Troubleshooting

Next Steps