Using Jenkins agents

The Jenkins architecture is designed for distributed build environments. It allows us to use different environments for each build project balancing the workload among multiple agents running jobs in parallel.

The Jenkins controller is the original node in the Jenkins installation. The Jenkins controller administers the Jenkins agents and orchestrates their work, including scheduling jobs on agents and monitoring agents. Agents may be connected to the Jenkins controller using either local or cloud computers.

The agents require a Java installation and a network connection to the Jenkins controller. View the 3 minute video below for a brief explanation of Jenkins agents.

What is a Jenkins Agent

Agent concepts

Jenkins agents provide executors that perform work when requested by the Jenkins controller. Agents can run Pipeline steps, freestyle jobs, and other jobs.

Specific capabilities of agents are often noted by assigning labels to the agents. An agent running on an Arm64 computer might be assigned the aarch64 label so that jobs can limit themselves to only run on agents with the Arm64 processor. An agent running with a code signing application might be assigned the code-signing label so that jobs that need to sign executables would run there.

Agents may be allowed to run any job or they may be restricted to only run jobs that are specifically assigned to the agent.

Number of executors

The number of executors determines how many concurrent tasks can be run on an agent. For Jenkins controllers, it is recommended to set this to 0 to avoid resource contention. Executors should be configured on agents (nodes) instead.

Why set executors to 0 on the controller? Setting executors to 0 ensures that the controller is dedicated to managing builds and coordinating agents, rather than executing builds itself. This improves stability and performance.

For instance, agents with specific capabilities can be configured with multiple executors to handle concurrent builds effectively.

Labels

Labels are used to group agents (nodes) based on specific criteria. They help in assigning jobs to specific agents. For example, you can label agents based on their operating system or hardware capabilities.

Example:

linux, windows, docker, high-memory

Labels can be assigned in the agent configuration settings.

Usage

This section defines how jobs are assigned to agents. Options include:

  • Use this node as much as possible: Jobs will be assigned to this node whenever possible.

  • Only build jobs with label expressions matching this node: Jobs will only be assigned if their label matches.

Configuring agents with Docker

Jenkins agents can be launched in physical machines, virtual machines, Kubernetes clusters, and with Docker images. Before configuring an agent, decide which side will initiate the connection.

Choose the connection direction

With an inbound agent connection, the agent initiates a connection to the Jenkins controller. The agent needs a reachable controller URL and, when using the inbound TCP protocol, the controller’s inbound agent port. WebSocket connections use the controller’s HTTP(S) endpoint instead.

Docker agent  ---- inbound TCP or WebSocket ---->  Jenkins controller
                   Agent initiates

This section is a step-by-step guide to the other direction: the Jenkins controller connects to the Docker agent over SSH.

Jenkins controller  ---- SSH ---->  Docker agent
                     Controller initiates

For SSH, the controller must be able to reach the agent. If both containers share a user-defined Docker network, connect to the agent by its container name and port 22; no host port needs to be published. If the controller is outside that network, publish a host port for the container’s SSH port and use the Docker host’s reachable address and that host port in Jenkins. Choose a host port that is reachable only by the controller, and restrict access with your host firewall.

Environment

To run this guide you will need a machine with:

  • Java installation

  • Jenkins installation

  • Docker installation

  • SSH key pair

If you need help to install Java, Jenkins and Docker please visit the section Installing Jenkins.

Generating an SSH key pair

To generate the SSH key pair, you have to execute a command line tool named ssh-keygen on a machine you have access to. It could be:

  • the machine on which your Jenkins controller runs

  • the host (if using containers)

  • a machine on which you have an agent running

  • or even your developer machine

The SSH key pair generation can be done on any operating system:

  • On Windows, you can use any OpenSSH installation such as Windows OpenSSH, the ssh-keygen that is included with git for Windows, or Cygwin

  • On Unix (Linux, macOS, BSD, etc.) you can use any OpenSSH installation packaged with your system as well

Note that you will have to be able to copy the key value to your controller and agent afterwards, so check that you can copy a file content into the clipboard beforehand.
  1. In a terminal window run the command: ssh-keygen -f ~/.ssh/jenkins_agent_key

  2. Provide a passphrase to use with the key (it can be empty)

  3. Confirm the output looks something like this:

    ubuntu@desktop:~$ ssh-keygen -f ~/.ssh/jenkins_agent_key
    Generating public/private rsa key pair.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /home/ubuntu/.ssh/jenkins_agent_key
    Your public key has been saved in /home/ubuntu/.ssh/jenkins_agent_key.pub
    The key fingerprint is:
    SHA256:XqxxjqsLlvDD0ZHm9Y2iR7zC6IbsUlMEHo3ffy8TzGs
    The key's randomart image is:
    +---[RSA 3072]----+
    |  o+             |
    | ...o  .         |
    |  .o .+ .        |
    |    o+.+ o o     |
    |  ... o.So* .    |
    |  o+ = +.X=      |
    | o oO + *..+     |
    |. oo.o o .E .    |
    | o... oo.. o     |
    +----[SHA256]-----+

Create a Jenkins SSH credential

  1. From your Jenkins dashboard, navigate to Manage Jenkins.

  2. In the Security section, select Credentials.

    Credentials option from Manage Jenkins page.

  3. Under Stores scoped to Jenkins, select Add Credentials from the global option.

    Add credentials option.

  4. Fill in the following information, as shown in the example, substituting your information as needed:

    • Kind: SSH username with private key

    • ID: jenkins

    • Description: The Jenkins SSH key

    • Username: jenkins

    • Private Key: Select Enter directly and then select Add to insert the content of your private key file (~/.ssh/jenkins_agent_key).

    • Passphrase: Enter the passphrase used to generate the SSH key pair (or leave it empty if you didn’t use one in the previous step).

      Credential configuration form filled in.

  5. Select Create to complete your credential configuration.

Creating your Docker agent

On Linux and macOS

Here we will use the docker-ssh-agent image to create the agent containers.

Choose the command that matches how your controller reaches the agent.

  1. If the controller is outside the agent’s Docker network, publish a host port for SSH:

    docker run -d --rm --name=agent1 -p <host-port>:22 \
      -e "JENKINS_AGENT_SSH_PUBKEY=$(cat ~/.ssh/jenkins_agent_key.pub)" \
      jenkins/ssh-agent:alpine-jdk25
  2. If the controller and agent share a user-defined Docker network, create the network if needed and start the agent on it. Do not publish a host port for this setup:

    docker network create jenkins
    docker run -d --rm --name=agent1 --network jenkins \
      -e "JENKINS_AGENT_SSH_PUBKEY=$(cat ~/.ssh/jenkins_agent_key.pub)" \
      jenkins/ssh-agent:alpine-jdk25

    If docker network create jenkins reports that the network already exists, continue with the docker run command. The controller must also be attached to this network.

Replace <host-port> with an available port on the Docker host, and do not type the angle brackets. If the chosen host port is already in use (including port 22 when an SSH server is running on the host), choose another available port, such as 4444. Use the same host port in the Jenkins SSH launcher. The container’s SSH port remains 22.

  1. Check that the container is running:

    docker ps --filter name=agent1

Both commands pass the contents of your public key file to the image. The private key belongs in the Jenkins credential created above; do not pass it to Docker.

On Windows

Here we will use the docker-ssh-agent image to create the agent containers. The jenkins/ssh-agent:jdk25 tag is a Linux container image, so Docker Desktop must be configured to run Linux containers.

  1. Read the public key into a PowerShell variable:

    $publicKey = (Get-Content "$Env:USERPROFILE\.ssh\jenkins_agent_key.pub" -Raw).Trim()
    docker run -d --rm --name=agent1 -p <host-port>:22 `
      -e "JENKINS_AGENT_SSH_PUBKEY=$publicKey" `
      jenkins/ssh-agent:jdk25

    Or, if the controller and agent share a user-defined Docker network, create the network if needed and start the agent on it without publishing a host port:

    docker network create jenkins
    docker run -d --rm --name=agent1 --network jenkins `
      -e "JENKINS_AGENT_SSH_PUBKEY=$publicKey" `
      jenkins/ssh-agent:jdk25

    If docker network create jenkins reports that the network already exists, continue with the docker run command. The controller must also be attached to this network.

    Both commands pass the public key contents to the image. Do not pass the path to the .pub file or the private key.

    Replace <host-port> with an available port on the Docker host, and do not type the angle brackets. If the chosen host port is already in use (including port 22 when an SSH server is running on the host), choose another available port, such as 4444. Use the same host port in the Jenkins SSH launcher. The container’s SSH port remains 22.

    1. Check that the container is running:

      docker ps --filter name=agent1

Verifying the SSH connection

When using a published host port, you can check the SSH key, host, and port before configuring the node. On Linux and macOS, run:

+

ssh -i ~/.ssh/jenkins_agent_key -p <host-port> jenkins@localhost java -version

+ On Windows PowerShell, run:

+

ssh -i "$Env:USERPROFILE\.ssh\jenkins_agent_key" -p <host-port> jenkins@localhost java -version

+ Replace <host-port> with the host port you chose above, without the angle brackets. For a controller and agent on the same Docker network without a published port, use the Jenkins node connection and build steps below to verify access instead.

Set up agent1 on Jenkins

  1. From your Jenkins dashboard, navigate to Manage Jenkins.

  2. Select Nodes.

    Manage node menu.

  3. Select New Node to create your agent.

  4. Enter your Node name, select the Permanent Agent option, and select Create.

  5. On the agent creation page fill in the fields:

    • Remote root directory: /home/jenkins/agent

    • Number of executors: 1

    • Labels: agent1

    • Usage: select Only build jobs with label expressions matching this node.

    • Launch method: select Launch agents via SSH.

      • Host: if the controller runs on the Docker host, use that host’s address (for a controller on the same machine, localhost). If the controller and agent share the jenkins Docker network, use agent1.

      • Port: use the host port you selected in the Docker command when connecting through the Docker host; use 22 when connecting to agent1 on the shared Docker network.

      • Credentials: select the jenkins SSH credential created above.

      • Host Key Verification Strategy: select Manually provided key and paste the agent’s SSH host public key. Display it with docker exec agent1 cat /etc/ssh/ssh_host_ed25519_key.pub on the Docker host. If you recreate the container, its generated host key may change; verify and update the configured key before reconnecting.

        The remote root directory /home/jenkins/agent is the default working directory for the Linux image. Keep the host, port, credential, and host key consistent with the Docker network or published-port setup you chose above.

        Node configuration page filled in.

  6. Select Save and agent1 will be registered, but offline for the time being. Select the agent1 node to view its status.

  7. The status page should show the message: This node is being launched. If that’s not the case, select Relaunch agent and wait a few seconds.

  8. After waiting, select the Log option to view the logs. At the bottom of the log, you should receive the message: Agent successfully connected and online.

If the agent remains offline, check the node log for connection, authentication, or host-key errors. Confirm that the controller can reach the Docker host or shared network, that the SSH credential contains the matching private key and username jenkins, and that the configured port matches the mapping. For a host mapping such as <host-port>:22, set the SSH launcher port to the selected host port; for containers sharing the jenkins network, use port 22.

Delegating the first job to agent1

  1. From your Jenkins dashboard select New Item.

  2. Enter a name, for example, First job on agent1.

  3. Select Freestyle project and select OK to create the job.

  4. Select the option Restrict where this project can be run.

  5. Enter the node label (agent1) in the Label Expression field.

    Label expression field with agent1 value.

    Be careful with white spaces before or after the label.

  6. Select the Execute shell option from the Build Steps dropdown;

  7. Add the commands echo $NODE_NAME and java -version in the Command field. The build log should show agent1 and the Java version supplied by the agent image.

    Entering the command for the build step.

  8. Select Save and then select Build Now.

  9. Wait a few seconds, and then go to Console Output page. You should receive output similar to:

    Console output of a successful build.

Restarting a Jenkins agent

This video provides instructions on how to restart a Jenkins agent using various methods.



Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

    


See existing feedback here.