Hardware Requirements

CPU

  • Architecture: x86_64/AMD64
  • Virtualization support (VMX or SVM)
  • KVM enabled
# Verify CPU support
grep -E 'svm|vmx' /proc/cpuinfo
# Verify KVM
ls /dev/kvm

Memory

  • Base: 100MB for runner service
  • Per Environment: 2GB minimum
  • Example sizing:
    • 3 environments: 6.1GB minimum
    • 5 environments: 10.1GB minimum
    • 10 environments: 20.1GB minimum

Storage

  • Minimum: 10GB free space
  • Recommended: 50GB+ for multiple environments
  • SSD recommended for performance
# Check free space
df -h

Operating System

Supported Distributions

  • Ubuntu 24.04 LTS
  • CentOS 9
  • Fedora 40
  • Other modern distributions (may need additional configuration)

Architecture Support

  • ✅ AMD64 (x86_64)
  • ❌ ARM64/AArch64 (not supported)

System Configuration

You don’t need to make these changes manually. The setup command will:

  • Check for all required configurations
  • Show you exactly what changes are needed
  • Guide you through making any necessary changes

The following sections describe what the setup will check and configure:

1. Kernel Modules

  • What: The following kernel modules are required:

    Network modules:

    • bridge: Network bridge support
    • br_netfilter: Bridge netfilter support
    • nf_tables: Netfilter tables
    • nf_nat: Network address translation
    • nf_conntrack: Connection tracking
    • xt_conntrack: Connection tracking netfilter module
    • tun: Network tunneling support

    Virtualization modules:

    • kvm: Base KVM module
    • kvm_intel (Intel CPUs) or kvm_amd (AMD CPUs): CPU-specific virtualization
  • Why: These modules enable:

    • Network isolation and routing between environments
    • Virtual machine creation and management
    • Secure network communication

2. Network Settings

  • What: Enable IP forwarding and bridge filtering

  • Why: Allows environments to access the internet and communicate securely

  • Changes:

    # Apply settings
    sudo sysctl -w net.ipv4.ip_forward=1
    sudo sysctl -w net.bridge.bridge-nf-call-iptables=1
    sudo sysctl -w net.bridge.bridge-nf-call-ip6tables=1
    
    # Make permanent
    sudo bash -c 'cat > /etc/sysctl.d/99-gitpod-runner.conf << EOF
    net.ipv4.ip_forward=1
    net.bridge.bridge-nf-call-iptables=1
    net.bridge.bridge-nf-call-ip6tables=1
    EOF'
    

3. UFW Configuration (if using UFW)

  • What: Allow forwarding in UFW firewall

  • Why: Required for environment network connectivity

  • Changes:

    # Edit /etc/default/ufw
    DEFAULT_FORWARD_POLICY="ACCEPT"
    
    # Reload UFW
    sudo ufw reload
    

Reverting Changes

To revert all system changes after uninstalling the runner:

# 1. Remove configuration files
sudo rm /etc/modules-load.d/gitpod-runner.conf
sudo rm /etc/sysctl.d/99-gitpod-runner.conf

# 2. Restore UFW settings (if modified)
sudo sed -i 's/DEFAULT_FORWARD_POLICY="ACCEPT"/DEFAULT_FORWARD_POLICY="DROP"/' /etc/default/ufw
sudo ufw reload

# 3. Restore system settings
sudo sysctl -w net.ipv4.ip_forward=0
sudo sysctl -w net.bridge.bridge-nf-call-iptables=0
sudo sysctl -w net.bridge.bridge-nf-call-ip6tables=0

# 4. Unload kernel module(s) (optional). Example:
sudo modprobe -r br_netfilter

Save your original network configuration before making changes if you need to restore exact previous values.

Connectivity

  • Outbound internet access required for:
    • Gitpod services
    • Container registries
    • Source code repositories

Network Access

  • Runner creates virtual networks
  • Environments can access local network
  • Consider security implications

User Permissions

Installation

Requires root/sudo for:

  • Installing Gitpod CLI
  • Setting capabilities
  • Configuring network
  • Setting up systemd service

Operation

  • Runs without root after setup
  • Service user needs network capabilities

Unsupported Configurations

❌ Will not work on:

  • Virtual machines
  • Cloud instances
  • ARM-based systems
  • Windows/macOS
  • Systems without hardware virtualization

Validation

The runner automatically validates these requirements during setup. When you run gitpod runner setup, it will check:

  • CPU virtualization support
  • KVM availability
  • Memory and disk space
  • Network configuration
  • Required system capabilities

If any requirements are not met, the setup will provide specific instructions for resolving the issues.

Next Steps

Once requirements are met:

  1. Set up your Linux runner
  2. Configure environment classes
  3. Set up repository access

If you encounter issues, check our troubleshooting guide.