> ## 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.

# Running as a Service

> Set up roboticks-runner as a system service with systemd (Linux) or launchd (macOS) for automatic startup.

# 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:

```bash theme={null}
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:

```bash theme={null}
# 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
```

<Note>
  If you prefer to run as your own user, change `User=roboticks` to `User=<your-username>` in the service file.
</Note>

### Enable and Start

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
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

```bash theme={null}
# Load and start
launchctl load ~/Library/LaunchAgents/io.roboticks.runner.plist

# Verify it's running
launchctl list | grep roboticks
```

### Manage the Service

```bash theme={null}
# 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/](https://nssm.cc/)
2. Install the service:

```powershell theme={null}
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

```powershell theme={null}
# 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:

```yaml theme={null}
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
```

<Warning>
  Running the runner in Docker requires mounting the Docker socket, which gives the container access to the host's Docker daemon.
</Warning>

## 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

<AccordionGroup>
  <Accordion title="Service fails to start">
    Check the logs for errors:

    ```bash theme={null}
    # 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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Service restarts frequently">
    Check logs for the restart reason. Common causes:

    * Out of memory (reduce `max_concurrent_jobs`)
    * Network connectivity issues
    * Docker daemon problems
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/runners/configuration">
    Customize runner settings
  </Card>

  <Card title="CI/CD Integration" icon="code-branch" href="/cli/ci-cd">
    Use runners in pipelines
  </Card>
</CardGroup>