Skip to main content

Install and run Self-Hosted runners

This guide covers installing, configuring, and operating the Tower Runner on your own infrastructure across Linux, macOS, Windows, and Docker.

Self‑Hosted Data Plane Mode

For an architectural overview and behavior of Self‑Hosted Data Plane mode, see: Data Plane → Self‑Hosted Data Plane

Download locations​

Get the full URL you need from the table below. Latest links are fixed; versioned links show an example (0.8.17).

PlatformFormatArchLatest URLVersioned example (0.8.17)
Debian/Ubuntu.debamd64https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner_amd64.debhttps://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner_0.8.17-1_amd64.deb
Debian/Ubuntu.debarm64https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner_arm64.debhttps://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner_0.8.17-1_arm64.deb
Linuxtar.gzx86_64https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-linux-x86_64.tar.gzhttps://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner-linux-x86_64-0.8.17.tar.gz
Linuxtar.gzaarch64https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-linux-aarch64.tar.gzhttps://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner-linux-aarch64-0.8.17.tar.gz
macOStar.gzarm64https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-macos-aarch64.tar.gzhttps://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner-macos-aarch64-0.8.17.tar.gz
macOStar.gzx86_64https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-macos-x86_64.tar.gzhttps://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner-macos-x86_64-0.8.17.tar.gz
WindowsMSIx64https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-x64.msihttps://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner-x64-0.8.17.msi
WindowsMSIarm64https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-arm64.msihttps://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner-aarch64-0.8.17.msi
WindowsZIPx86_64https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-windows-x86_64.ziphttps://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner-windows-x86_64-0.8.17.zip
WindowsZIPaarch64https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-windows-aarch64.ziphttps://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner-windows-aarch64-0.8.17.zip

Note: You can verify downloads by appending .sha256 to any file URL above to retrieve its SHA‑256 checksum.

Requirements for running the Self-Hosted runner​

  • A Tower account and API key
  • Outbound network access to *.tower.dev over TCP 443
  • Platform and privileges:
    • Linux: x86_64 or ARM64; root/sudo privileges for service install
    • Windows: x64 or ARM64; Administrator privileges for MSI or service install
    • macOS: x86_64 or ARM64; interactive shell usage

Linux (Debian/Ubuntu) — .deb package (recommended)​

  1. Download and install from S3
# Latest (amd64)
curl -L -O https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner_amd64.deb
sudo dpkg -i tower-runner_amd64.deb

# Latest (arm64)
curl -L -O https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner_arm64.deb
sudo dpkg -i tower-runner_arm64.deb

# Versioned example (amd64)
curl -L -O https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner_0.8.17-1_amd64.deb
sudo dpkg -i tower-runner_0.8.17-1_amd64.deb
  1. Configure API key
sudo $EDITOR /etc/tower-runner/tower-runner.env
# Set: TOWER_API_KEY=your-api-key-here
  1. Start and verify
sudo systemctl enable --now tower-runner
sudo systemctl status tower-runner
journalctl -u tower-runner -f

The package installs a:

  • Binary at /usr/bin/tower-runner
  • Systemd unit tower-runner.service
  • Config file at /etc/tower-runner/tower-runner.env (preserved across upgrades)

Linux (other)​

Download the tarball from S3

# Latest (x86_64)
curl -L https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-linux-x86_64.tar.gz | tar -xz
# Latest (arm64)
curl -L https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-linux-aarch64.tar.gz | tar -xz
# Specific version (x86_64)
export RUNNER_VERSION=0.8.17
curl -L "https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner-linux-x86_64-${RUNNER_VERSION}.tar.gz" | tar -xz

sudo mv tower-runner /usr/local/bin/
sudo chmod +x /usr/local/bin/tower-runner

macOS — binary​

# Latest (Apple Silicon / arm64)
curl -L https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-macos-aarch64.tar.gz | tar -xz

# Latest (Intel / x86_64)
curl -L https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-macos-x86_64.tar.gz | tar -xz

# Versioned example (Apple Silicon)
curl -L https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner-macos-aarch64-0.8.17.tar.gz | tar -xz

chmod +x tower-runner
sudo mv tower-runner /usr/local/bin/

# Authenticate (preferred: .env file in the working directory)
echo "TOWER_API_KEY=your-api-key-here" > .env
## Or for a one-off shell session:
export TOWER_API_KEY=your-api-key-here
# You can also: tower login (via CLI) to create a session
tower-runner start

Windows — MSI installer (recommended)​

# Latest (x64)
Invoke-WebRequest -Uri "https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-x64.msi" -OutFile "tower-runner.msi"
# Latest (arm64)
Invoke-WebRequest -Uri "https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-aarch64.msi" -OutFile "tower-runner.msi"
# Versioned example (x64)
Invoke-WebRequest -Uri "https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner-x64-0.8.17.msi" -OutFile "tower-runner.msi"

msiexec /i tower-runner.msi /qb
notepad $env:ProgramData\tower-runner\tower-runner.env  # Set TOWER_API_KEY
Start-Service -Name TowerRunner
Get-Service -Name TowerRunner

Windows — ZIP + PowerShell scripts (alternative)​

# Latest (x86_64)
Invoke-WebRequest -Uri "https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-windows-x86_64.zip" -OutFile "tower-runner.zip"
# Latest (arm64)
Invoke-WebRequest -Uri "https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/latest/tower-runner-windows-aarch64.zip" -OutFile "tower-runner.zip"
# Versioned example (x86_64)
Invoke-WebRequest -Uri "https://tower-packages.s3.us-east-1.amazonaws.com/releases/tower-runner/0.8.17/tower-runner-windows-x86_64-0.8.17.zip" -OutFile "tower-runner.zip"

Expand-Archive -Path "tower-runner.zip" -DestinationPath "C:\\Program Files\\tower-runner"
cd "C:\\Program Files\\tower-runner"
./install-service.ps1

notepad $env:ProgramData\tower-runner\tower-runner.env  # Set TOWER_API_KEY
Start-Service -Name TowerRunner
Get-Service -Name TowerRunner

Docker — containerized runner​

# Latest tag
docker run -d --name tower-runner --restart unless-stopped \
  -e TOWER_API_KEY="your-api-key-here" \
  towerhq/tower-runner:latest

# Versioned example
docker run -d --name tower-runner-089 --restart unless-stopped \
  -e TOWER_API_KEY="your-api-key-here" \
  towerhq/tower-runner:0.8.17

# Logs
docker logs -f tower-runner

Notes:

  • Image name: towerhq/tower-runner
  • Tags: latest and semantic versions (e.g., 0.8.17)