ID: swarm


The Swarm plugin enables nodes to join a nearby Jenkins controller, thereby forming an ad-hoc cluster. This plugin makes it easier to scale a Jenkins cluster by spinning up and tearing down new agents, enabling team members to contribute compute resources to a build farm or to attach agents to which the Jenkins controller cannot initiate connections.

This plugin consists of two pieces:

  1. A self-contained client that can join an existing Jenkins controller.

  2. A plugin that needs to be installed on the Jenkins controller to accept Swarm clients.

With the Swarm client, a person who is willing to contribute some of his computing power to the cluster just needs to run a virtual machine with the Swarm client and the cluster gets an additional agent. Because the Swarm client is running on a separate VM, there is no need to worry about the builds/tests interfering with the host system or altering its settings unexpectedly.

Getting started

  1. Install the Swarm plugin from the Update Center.

  2. Ensure your agent is running version 8 or later of the Java Runtime Environment (JRE). The recommendation is to use the same JRE distribution and version as the controller.

  3. Download the Swarm client from ${JENKINS_URL}/swarm/swarm-client.jar or Jenkins repository on your agent.

  4. Run the Swarm client with java -jar path/to/swarm-client.jar -url ${JENKINS_URL} -username ${USERNAME} and one of the authentication options as described in the Global Security Configuration documentation. There are no other required command-line options; run with the -help option to see the available options.

Available options

$ java -jar swarm-client.jar -help

Name Description

-config FILE

YAML configuration file containing the options.


Delete any existing agent with the same name. (default: false)

-description VAL

Description to be put on the agent.


Disable client’s unique ID. (default: false)


Disable SSL verification in the HTTP client. (default: false)


Disable Remoting working directory support and run the agent in legacy mode. (default: false)

-e (--env)

An environment variable to be defined on this agent. It is specified as `key=value'. Multiple variables are allowed.

-executors N

Number of executors (default: number of CPUs)


Fail if the requested Remoting working directory or internal directory is missing. (default: false)

-fsroot FILE

Remote root directory. (default: .)

-help (--help, -h)

Show the help screen (default: false)

-internalDir FILE

The name of the directory within the Remoting working directory where files internal to Remoting will be stored.

-jar-cache FILE

Cache directory that stores JAR files sent from the controller.

-labels VAL

Whitespace-separated list of labels to be assigned for this agent. Multiple options are allowed.

-labelsFile VAL

File location with space delimited list of labels. If the file changes, the client is restarted.

-maxRetryInterval N

Max time to wait before retry in seconds. Default is 60 seconds. (default: 60)

-mode MODE

The mode controlling how Jenkins allocates jobs to agents. Can be either `normal' (use this node as much as possible) or `exclusive' (only build jobs with label expressions matching this node). Default is `normal'. (default: normal)

-name VAL

Name of the agent.


Do not retry if a successful connection gets closed. (default: false)

-password VAL

The Jenkins user API token or password.

-passwordEnvVariable VAL

Environment variable containing the Jenkins user API token or password.

-passwordFile VAL

File containing the Jenkins user API token or password.

-pidFile VAL

File to write PID to. The client will refuse to start if this file exists and the previous process is still running.

-prometheusPort N

If defined, then start an HTTP service on this port for Prometheus metrics. (default: -1)

-retry N

Number of retries before giving up. Unlimited if not specified. (default: -1)


The mode controlling retry wait time. Can be either `none' (use same interval between retries) or `linear' (increase wait time before each retry up to maxRetryInterval) or `exponential' (double wait interval on each retry up to maxRetryInterval). Default is `none'. (default: NONE)

-retryInterval N

Time to wait before retry in seconds. Default is 10 seconds. (default: 10)

-sslFingerprints VAL

Whitespace-separated list of accepted certificate fingerprints (SHA-256/Hex), otherwise system truststore will be used. No revocation, expiration or not yet valid check will be performed for custom fingerprints! Multiple options are allowed. (default: )

-t (--toolLocation)

A tool location to be defined on this agent. It is specified as `toolName=location'.

-tunnel VAL

Connect to the specified host and port, instead of connecting directly to Jenkins. Useful when connection to Jenkins needs to be tunneled. Can be also HOST: or :PORT, in which case the missing portion will be auto-configured like the default behavior

-url (-master) VAL

The complete target Jenkins URL like `http://server:8080/jenkins/'.

-username VAL

The Jenkins username for authentication.


Connect using the WebSocket protocol. (default: false)

-webSocketHeader NAME=VALUE

Additional WebSocket header to set, e.g. for authenticating with reverse proxies. To specify multiple headers, call this flag multiple times, one with each header.

-workDir FILE

The Remoting working directory where the JAR cache and logs will be stored.


Report issues and enhancements in the Jenkins issue tracker. Use the swarm-plugin component in the JENKINS project.


Refer to our contribution guidelines.