Launching Jenkins Inbound Agents with Java

Article ID:360055603052
2 minute readKnowledge base


  • I would like to launch inbound agents to connect to a Jenkins controller

  • When launching inbound agents, the launch fails with arguments passing errors such as "<option>" is not a valid option, "<option>" is required or option "<option1>" cannot be used with the option(s) <list of options>


There are mainly 2 recommended ways of starting an inbound agent with Java, and depending on the approach chosen, different options and arguments can be used:

  • The more common and simplistic approach is by downloading a JNLP file and using the Launcher, typically: java -jar agent.jar -jnlpUrl <jnlpUrl> ....

  • The raw approach, by executing the Remoting Main entrypoint, typically: java -cp agent.jar hudson.remoting.jnlp.Main -headless ...

There is no recommendation whether to use one or another. The raw approach allow more fine-grained configuration.

Launcher / JNLP File

The most common way, that is also advertised in the Node page, is by using the remoting Launcher and pass the URL of the JNLP File:

java -jar agent.jar -jnlpUrl "${JENKINS_URL}"/computer/"${AGENT_NAME}"/jenkins-agent.jnlp ....

This command retrieve the jenkins-agent.jnlp file at "${JENKINS_URL}"/computer/"${AGENT_NAME}"/jenkins-agent.jnlp via HTTP/S. It is an XML file and can be read with cat or a text editor. That file contains the options and arguments that will be passed to the hudson.remoting.jnlp.Main class of remoting to start the agent (like the raw approach does).

Use java -jar agent.jar -help to see the options.

Raw approach with hudson.remoting.jnlp.Main

Another way, not advertised in the Node page, is to add agent.jar to the CLASSPATH and execute the hudson.remoting.jnlp.Main directly:

java -cp agent.jar hudson.remoting.jnlp.Main ...

This method is a raw command to which you need to provide all necessary arguments. This is the method used in the Inbound Agent images such as jenkins/inbound-agent and cloudbees/cloudbees-core-agent to launch the agent.

Use java -cp agent.jar hudson.remoting.jnlp.Main -help to see the options.