This guide covers how to keep your Linux runner updated and running smoothly.

​
Version Management

The runner periodically checks for newer versions and logs a message when updates are available. You can see the current version of your runner in the Gitpod UI under Settings -> Runners.

​
Updating the Runner

Updates are performed manually using the Gitpod CLI. To update your runner:
  1. Stop the runner
    • If running in the terminal, press Ctrl+C
    • If running as a service: 
      sudo systemctl stop gitpod-runner
      Stopping the runner does not stop any running environments. The environments will continue running, but the runner will not process any new start/stop requests or report environment status updates to Gitpod while it is stopped.
  2. Run the update command: 
    gitpod runner update
  3. Restart the runner
    • If running in the terminal: 
      gitpod runner run
    • If running as a service: 
      sudo systemctl start gitpod-runner

​
Monitoring

​
Logs

  • If running in the terminal, logs are printed directly to stdout
  • If running as a systemd service, view logs with: 
    journalctl -u gitpod-runner
Use the -f flag to follow logs in real-time: 
journalctl -u gitpod-runner -f

​
Runner Status

You can monitor your runner’s status in the Gitpod UI under Settings -> Runners. The status will show:
  • Connection state
  • Version information
  • Any warning or error messages

​
Resource Management

The Linux runner runs environments as virtual machines on your host. The runner has a built-in limit of 10 environments (excluding deleted environments) per runner. To maintain good performance:
  • Monitor system resource usage (CPU, memory, disk)
  • Consider the number of concurrent environments
  • Keep sufficient free disk space for environment data

​
Best Practices

  1. Regular Updates
    • Watch for update notifications in the logs
    • Plan updates during low-usage periods
    • Keep the runner up to date for the latest features and fixes
  2. Log Management
    • If using systemd, consider configuring log rotation
    • Monitor logs periodically for warnings or errors
    • Keep track of resource usage patterns
  3. Backup Considerations
    • The runner stores environment data in ~/gitpod-runner
    • Consider this location in your backup strategy if needed
  4. System Maintenance
    • Keep the host system updated
    • Monitor system health
    • Maintain sufficient free resources

​
Common Maintenance Tasks

​
Checking Runner Status

# If running as a service
sudo systemctl status gitpod-runner

​
Restarting the Runner

# If running as a service
sudo systemctl restart gitpod-runner

​
Deleting the Runner

To completely remove a runner:
  1. Delete the runner from Gitpod in Settings -> Runners
  2. On your Linux machine: a. Stop the runner process:
    • If running in the terminal, press Ctrl+C or terminate the gitpod runner run process
    • If running as a systemd service: 
      sudo systemctl stop gitpod-runner
    b. Remove runner files and environment data: 
    rm -rf ~/gitpod-runner
    c. If you set up a systemd service, remove it: 
    sudo systemctl disable gitpod-runner
sudo rm /etc/systemd/system/gitpod-runner.service
    d. Remove the sudoers configuration: 
    sudo rm /etc/sudoers.d/gitpod-runner

​
Next Steps