Agent8 for Jenkins
Run Jenkins agents on hosts stuck on Java 8, 11 or 17.
Jenkins now requires Java 21 on the controller and on every agent. With Agent8 the controller moves on, and the old build host keeps its Java and stays an ordinary node.
# 1. fetch the installer $ curl -fsSLO https://raw.githubusercontent.com/\ keelinfra/agent8/main/install.sh # 2. match the controller, swap the jar $ sh install.sh --url https://jenkins.example.com/ \ --replace /path/to/agent.jar # 3. restart with the same command as before $ java -jar /path/to/agent.jar -url ... -name aix71
The controller upgrades. The build host doesn't have to.
What keeps working on the old host
- Labels and executors
shand file stepsjunitandstash- Pipeline, Git checkout (JGit) and credentials
- Aborts and agent restarts mid-build
- The script console
Where it runs today
Linux is tested in CI on every change. Agent8 has also been tested on AIX (IBM Java 8), Solaris (Oracle Java 8) and HP-UX (Itanium, HP Java 8); those platforms are not in CI. Tell us what your hosts run.
| Build host | Java | Status |
|---|---|---|
| Linux, including RHEL/CentOS 6 | HotSpot 8 | Tested in CI |
| Linux, IBM Semeru (OpenJ9, the JVM family of IBM Java 8) | OpenJ9 8 | Tested in CI · best effort |
| Linux | HotSpot 11, 17 | Tested in CI (LTS) |
| AIX 7.1 / 7.2 / 7.3 | IBM Java 8 | Tested |
| Solaris | Java 8 | Tested |
| HP-UX (Itanium) | Java 8 | Tested |
OpenJ9 and IBM Java (J9) are outside Jenkins' own support. Agent8 tests OpenJ9 8 in CI and fixes the J9 problems it finds, best effort; report them on Agent8's issues.
One script, plain sh, any old Unix
It asks your controller
install.sh reads the remoting version of the controller's
agent.jar and downloads the Agent8 release built for it, in the build for the
host's Java. If there is none yet, it says so and uses the latest release.
It checks before it swaps
Downloads are checked against sha256sums.txt and test-started on the local
Java. The old jar is kept, and --restore puts it back.
You restart as usual
Same java -jar command, same service script. Offline hosts copy the
jars and sha256sums.txt and use --from DIR; fleets use the
Ansible playbook.
Releases are named after the Jenkins version they were tested with. Your version is at the bottom right of every Jenkins page.
All releases →Full options, the Ansible playbook and troubleshooting are in the README. Background: Jenkins requires Java 21. What happens to your AIX 7.1 and RHEL 6 build hosts?
The error that brings people here
After a controller upgrade, an agent on Java 8, 11 or 17 fails to start with:
java.lang.UnsupportedClassVersionError: hudson/remoting/Launcher has been compiled by a more recent version of the Java Runtime (class file version 65.0), this version of the Java Runtime only recognizes class file versions up to 52.0
Class file version 65.0 is Java 21 (61.0 is Java 17, 55.0 is Java 11); 52.0 is Java 8.
If the host can install a newer Java, do that. If it can't, as on AIX, Solaris or HP-UX, or
where the JDK must stay as it is, install Agent8 on it.
On an SSH node that still shows this error, set the node's Java Path to the
java file Agent8 installed.
Questions teams ask first
Is this an official Jenkins project?
No. Agent8 is independent and not endorsed or supported by the Jenkins project. Report problems on its GitHub issues, not the Jenkins tracker.
Why not run agent.jar on Java 21 and build with the old JDK?
If the host can install Java 21, do that and keep building with the old JDK; you don't need Agent8. It is for hosts that can't, such as AIX 7.1, HP-UX on Itanium and Solaris. Not sure which yours is? Ask us.
Why not run the build in a container?
That works for many RHEL 6 builds, and RHEL 6 x86_64 hosts can also install Amazon Corretto 21 or Azul Zulu 21 and run the stock agent. Neither covers builds that must run natively on AIX, Solaris or HP-UX hardware.
Does any controller setting matter?
Only if the Versions Node Monitors plugin (versioncolumn) is installed. Its
JVM Version monitor takes Agent8 nodes offline seconds after they connect, so set it not to
disconnect. Its Remoting Version monitor does the same when the agent's build differs from
the controller's. The README has
the configuration-as-code snippet.
What happens when we upgrade the controller?
Rerun install.sh (or the playbook) and restart the agent. Jenkins refuses
agents older than a minimum remoting version that it raises over time: Jenkins 2.586
already refuses the Agent8 build for 2.462.3. Which upgrade paths load every plugin, and where Java
has to change on the way, is in the upgrade matrix.
What hasn't been tested yet, and what doesn't work?
Plugins that run their own code on the agent beyond Git checkout (JGit and
command-line git) and credentials, such as Docker or artifact upload steps, are untested.
The Maven project type does not work: it starts its own JVM, which Agent8 does not reach.
Run Maven from a Pipeline or freestyle shell step (sh 'mvn ...') instead.
The README keeps the
list.
Which launch methods work?
Inbound agents, started with java -jar agent.jar, and the SSH Build Agents
launcher: set the node's Java Path to the java file
install.sh writes, and it runs Agent8 instead of the stock jar the launcher
copies.
What is the license?
Agent8's own code is MIT. Its jars also contain Jenkins remoting (MIT), ASM (BSD-3-Clause)
and JvmDowngrader classes (LGPL-2.1), and each release ships JvmDowngrader itself as
jvmdg.jar (LGPL-2.1, unmodified).
Rolling out to AIX, Solaris or HP-UX, or a whole fleet?
Agent8 is free. If you need support, we offer it as a paid service: pilots on your platform, plugin compatibility checks and yearly support. The first answer is free and in writing, within two business days. Pricing →