Skip to content

Upgrading the Runner

Keeping your NodeZero Runner current ensures that it stays compatible with the latest NodeZero platform, benefits from ongoing reliability and security fixes, and continues to launch tests reliably.

An upgraded Runner benefits from ongoing improvements to job scheduling, Docker deployment, and API communication. Upgrades are required to use newer automation features, such as touchless deployment and auto‑injected credentials. Also, upgrades simplify troubleshooting, and prevent unexpected breakage as the platform evolves.

Upgrade your installation using one of the methods below.

Upgrade Runner from Portal

You can upgrade a Runner easily from the NodeZero Portal's UI. On the Pentests > Runners page, open the Actions () menu to the right of any Runner.

Here, a single click on the Upgrade option enables you to update the Runner without redeploying your host.

NodeZero Runner's Actions menu, showing Upgrade optionI

Upgrading Runner from NodeZero Portal UI

Behind the scenes, this option:

  • Runs the CLI upgrade flow (that is, runs h3 upgrade on the host), to download and install the latest supported version of h3‑cli.

  • Restarts the Runner process to use the new CLI version.

  • Reports in to NodeZero as upgraded.

  • Does not change existing pentest data, configurations, templates, or credentials in the NodeZero Portal. The update applies only to the CLI bits and Runner service on the selected host.

Verify an upgrade

After allowing a short delay for the upgrade to complete, refresh the Runners page and open the selected Runner's details.

Check the Command History to confirm that the upgrade completed successfully (exit status 0). Check the Last Contact to confirm an up‑to‑date last heartbeat.

Upgrade Runner via CLI

A CLI upgrade also upgrades the Runner. If you prefer to manage the Runner and its underlying CLI directly on the host, you can instead log in and run h3 upgrade – or follow any of the other options listed at Upgrade the CLI. You can incorporate the CLI and script options into into your own automation (for example, change-management pipelines).

When to upgrade a Runner

Beyond general guidance to keep your Runners current, you should especially upgrade Runners when:

  • You want to make sure a Runner is on the latest CLI before running or scheduling tests.

  • You see guidance in release notes, or from Horizon3 Support, that a Runner upgrade is required to incorporate a new feature or fix.

  • You want to standardize multiple Runners on the same CLI version.

Limitations and troubleshooting

Keep in mind these considerations around upgrading a Runner, especially through the NodeZero Portal UI:

  • Minimum CLI version: Very old versions of h3‑cli do not support the Portal's Upgrade option. You'll need to upgrade the CLI version from the host's command line before you can run upgrades from the UI.

  • Runner availability during upgrade: While the Runner is upgrading and restarting, it cannot launch new internal pentests. Any pentests assigned to that Runner will wait until the Runner is back online. This is typically a brief interval. But if that Runner is the only one in a critical environment, with scheduled time‑sensitive or long‑running tests, you might prefer to upgrade outside peak hours.

  • Host permissions and environment: An upgrade might fail because the host environment or permissions prevent the CLI from downloading or writing files (for example, due to an invalid working directory or insufficient permissions). You'll see these failures reflected with error statuses in the Runner’s recent commands and logs.

  • No “already latest” check in UI: The NodeZero Portal will execute a requested Upgrade process without first checking whether the Runner is already using the latest CLI version. This is harmless, but just causes needless network traffic and Runner downtime.