Workiva Support Center

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), and gzip(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

1. Extract GroundRunner.zip to a temporary directory.
2. Open the Services console: press Win + R, type services.msc, and press Enter.
3. Find GroundRunner in the list, right-click it, and select Stop. 
4. Wait for the status to show Stopped.
5. Back up the existing binaries.
   In File Explorer, navigate to the GroundRunner installation directory and copy GroundRunner.exe and GroundRunnerMonitor.exe and any configuration files to a backup location (e.g. rename them to GroundRunner.exe.bak and GroundRunnerMonitor.exe.bak).
6. Replace the binaries by copying GroundRunner.exe and GroundRunnerMonitor.exe from the extracted directory into the installation directory, overwriting the existing files.
7. Back in the Services console, right-click GroundRunner and select Start. 
8. 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.

1. Extract the artifacts in the zip file.

   Note: Extracting the zip file to /tmp/groundrunner-update is used for exemplary purposes. You can extract the zip wherever fits best with your organization's policies.

   unzip GroundRunner.zip -d /tmp/groundrunner-update

2. 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.

3. 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.

4. Replace the binaries:

   cd /path_to_groundrunner_install_dir
   cp /tmp/groundrunner-update/GroundRunner .
   cp /tmp/groundrunner-update/GroundRunnerMonitor .

5. Set executable permissions:

   chmod +x GroundRunner GroundRunnerMonitor

   Note: If your GroundRunner is run by a specific system user, you may need to chown the new executables.

6. Start the service:

   sudo systemctl start <service-name>

7. Check the status of the service to ensure it is healthy:

   sudo systemctl status <service-name>

8. 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:

1. Stop the GroundRunner service as described above.
2. Rename the installed GroundRunner.exe and GroundRunnerMonitor.exe files.
3. Copy GroundRunner.exe.bak and GroundRunnerMonitor.exe.bak from the backup location to the installation directory. 
4. Rename these files by removing the ".bak" extension.
5. 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 (GroundRunner and GroundRunnerMonitor on Linux, and GroundRunner.exe and GroundRunnerMonitor.exe on 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.