Setting up Linux Runners
This guide walks you through setting up a Linux runner. Before starting, ensure your system meets the requirements.
Prerequisites
- Admin access to your Gitpod organization
- Root/sudo access on your Linux machine
- A machine meeting all system requirements
Installation Steps
1. Create Linux Runner in Gitpod
First, create a runner in your Gitpod organization:
- Go to Settings -> Runners in your Gitpod organization
- Click Set up a new runner, and select Linux
- Choose a name for your runner and click Create
- Keep this page open - it will guide you through the remaining setup steps and automatically transition to repository access configuration once the runner is running
2. Install Gitpod CLI
On your Linux machine, install the Gitpod CLI:
3. Set up Runner
Run the setup command shown in the Gitpod UI in step 1:
The setup will:
- Validate system requirements
- Configure networking
- Set required permissions
- Download necessary components
If any requirements are not met, the setup will provide specific instructions for resolving the issues. Re-run the setup command after resolving any issues until it completes successfully.
4. Configure Permissions
During setup, the runner will check if it can set the required network capabilities. If it cannot, you’ll be prompted to add specific rules to your sudoers configuration.
Follow the instructions provided by the setup command, which will typically include:
- Copy the suggested sudoers rules, these should look like this (replacing
YOUR_USERNAME
with your user): - Open the sudoers file with:
- Add the provided rules and save the file
These permissions allow the runner to:
- Set required network capabilities on its binaries without requiring full sudo access
- Automatically update itself without manual intervention
- Maintain proper isolation between environments
This approach is more secure than granting full sudo access because it:
- Limits elevated permissions to only the specific setcap command
- Restricts which binaries can receive capabilities
- Specifies exactly which capabilities can be granted
- Eliminates the need for password prompts during updates
5. Start Runner
Keep this command running to maintain the runner’s operation. The runner will check for new environments to start and manage existing ones.
Optional: Systemd Service Setup
To run the runner as a system service, create a systemd service file:
- Create the service file:
- Add this configuration:
Make sure to replace
YOUR_USER_HERE
with your actual system username (whoami
).
- Start and enable the service:
- Check the service status:
- Check the service logs:
Repository Access
Before the runner can be used to launch environments, configure repository access by following our repository access guide.
Environment Classes
Configure environment classes to define the resources allocated to each environment. See our environment classes guide.
The Linux runner creates a default set of environment classes based on the resources available on the host machine.
Next Steps
- Share runner with your team
- Review maintenance guide for updates and maintenance
- Review troubleshooting guide if you encounter issues
Monitoring
Monitor your runner through:
- Gitpod UI (Settings -> Runners)
- System logs:
Common Setup Issues
If the setup fails, check:
- System meets all requirements
- Network/firewall configuration
- Virtualization support is enabled in BIOS
- Sufficient disk space and memory
- Sudoers configuration is set correctly for automatic capability setting
For more help, see our troubleshooting guide.
Was this page helpful?