Follow these instructions to replace the GroundRunner and GroundRunnerMonitor binaries on a host machine with a newer version.
Important planning notes
- The GroundRunner service does not support graceful shutdown. When the service is stopped, any in-flight operations are terminated immediately. Results from those operations will be lost and the commands will need to be re-run.
- Because stopping the service is disruptive, we strongly recommend that you coordinate a deployment window with your stakeholders before performing the update, and make sure that no critical jobs are running or scheduled to run during the maintenance period.
Prerequisites (all platforms)
- Check to see if you need to update. The current version (as of June 1, 2026) is 9.21.1.
See How do I check the version of a GroundRunner? to learn what GroundRunner version you are using.
If your GroundRunner is out of date, the following banner will be displayed. - If your GroundRunner is out of date, record the version number shown in the Version field.
For Windows platforms
- The Windows
GroundRunner.zip, obtained from Workiva.
(See Install and manage GroundRunners for details.) - Administrator permissions for both:
- The machine where the GroundRunner is installed.
- The directory where the binaries are installed.
- Permission to stop and start the GroundRunner service.
For Linux platforms
- The Windows
GroundRunner.zip, obtained from Workiva.
(See Install and manage GroundRunners for details.) - The Linux utilities
unzip(1),tar(1), andgzip(1)must be installed (these are standard in most installations). - File ownership permissions (chown).
- Administrator permissions for both:
- The machine where the GroundRunner is installed.
- The directory where the binaries are installed.
- Permission to stop and start the GroundRunner service.
Windows installation
- Extract
GroundRunner.zipto a temporary directory. - Open the Services console: press
Win + R, typeservices.msc, and press Enter. - Find GroundRunner in the list, right-click it, and select Stop.
- Wait for the status to show Stopped.
- Back up the existing binaries.
In File Explorer, navigate to the GroundRunner installation directory and copyGroundRunner.exeandGroundRunnerMonitor.exeand any configuration files to a backup location (e.g. rename them toGroundRunner.exe.bakandGroundRunnerMonitor.exe.bak). - Replace the binaries by copying
GroundRunner.exeandGroundRunnerMonitor.exefrom the extracted directory into the installation directory, overwriting the existing files. - Back in the Services console, right-click GroundRunner and select Start.
- Verify the status shows Running.
Linux (systemd) installation
These instructions are for standard non-security-enhanced Linux systems. If your host runs SELinux, AppArmor, or other security software, see Mandatory Access Control (SELinux / AppArmor) at the end of this section.
-
Extract the artifacts in the zip file.
Note: Extracting the zip file to
/tmp/groundrunner-updateis used for exemplary purposes. You can extract the zip wherever fits best with your organization's policies.unzip GroundRunner.zip -d /tmp/groundrunner-update
-
Stop the running process. If using systemd, use this command:
sudo systemctl stop <service-name>
IMPORTANT NOTE: If you do not have your GroundRunner configured as a systemd service, please set it up as a systemd service before performing the update. Documentation about how to configure a systemd service can be found via your Linux distribution's documentation. If you use a non-systemd Linux distribution, please consult your distribution's documentation.
-
Back up binaries and configs in the GroundRunner directory:
cd /path_to_groundrunner_install_dir tar czvf groundrunner.bak.tar.gz GroundRunner* *config config* monitor.version
Note: You are welcome to backup the entirety of the install directory (i.e. including logs and other folders/files) but that can create an extremely large backup file.
-
Replace the binaries:
cd /path_to_groundrunner_install_dir cp /tmp/groundrunner-update/GroundRunner . cp /tmp/groundrunner-update/GroundRunnerMonitor .
-
Set executable permissions:
chmod +x GroundRunner GroundRunnerMonitor
Note: If your GroundRunner is run by a specific system user, you may need to
chownthe new executables. -
Start the service:
sudo systemctl start <service-name>
-
Check the status of the service to ensure it is healthy:
sudo systemctl status <service-name>
-
Clean up:
rm -rf /tmp/groundrunner-update
Mandatory access control (SELinux / AppArmor)
If the host enforces a mandatory access control policy (SELinux, AppArmor, or similar), replacing binaries on disk can cause the service to fail.
Refer to your distribution's documentation for managing security policies around custom services.
Note: Other security software — such as FAPOLICYD, IMA/EVM, or custom file integrity monitoring — may also block execution of replaced binaries. If the service fails to start after an update and you have ruled out SELinux/AppArmor, check whether any additional security frameworks on your system require updated trust lists or file signatures.
Verification
You can confirm the GroundRunner is active and its version is correct by following the instructions provided in How do I check the status of a GroundRunner?
We encourage you to create and run a "pilot chain" that runs a test set of commands on the GroundRunner to ensure proper installation.
We also encourage you to monitor your system and the GroundRunner's activity immediately after updating and restarting it. This allows you to be confident that it is running correctly. You can do this using a CLI command to stream and view new log entries as they happen.
For Windows
To view the end of the log file using PowerShell, enter the following:
Get-Content -Path "C:\path_to_\output.log" -Tail 10 -Wait
This keeps the PowerShell window open and streams new log entries in real time. -tail 10 loads the last 10 lines immediately.
For Linux
To view the end of the log file and stream new entries in real time, enter the following:
tail -f /path_to/output.log
Rollback
If the new version is not working correctly, you can roll back to the previous version by following these steps:
- Stop the GroundRunner service as described above.
- Rename the installed
GroundRunner.exeandGroundRunnerMonitor.exefiles. - Copy
GroundRunner.exe.bakandGroundRunnerMonitor.exe.bakfrom the backup location to the installation directory. - Rename these files by removing the ".bak" extension.
- Restart the GroundRunner service by following the appropriate steps described above.
Note: These same instructions apply to Linux GroundRunners, but you will need to extract the binaries from the backup tarball.
Notes
-
Do not rename the binaries. The auto-upgrade mechanism relies on the default executable names (
GroundRunnerandGroundRunnerMonitoron Linux, andGroundRunner.exeandGroundRunnerMonitor.exeon Windows) to detect and apply future updates. Renaming them will break automatic upgrades. - macOS is supported for development purposes only. It is not a supported production platform.
- Other service managers: The examples above use systemd (Linux) and the Windows Service Control Manager. If your environment uses a different service manager or process supervisor, perform the equivalent stop, replace, and start steps for your configuration.
- By default, GroundRunners use a local administrative account without access to remote resources such as shared drives. To access a shared resource such as a Windows UNC path, start the GroundRunner under a user account with adequate privileges to the resource. If using a user account other than the default local system administrator, grant it permissions to manage the GroundRunner's installation directory to enable automatic updates.