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.
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.
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 For instance, agents with specific capabilities can be configured with multiple executors to handle concurrent builds effectively. |
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.
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.
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.
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. |
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:
|
| 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. |
In a terminal window run the command: ssh-keygen -f ~/.ssh/jenkins_agent_key
Provide a passphrase to use with the key (it can be empty)
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]-----+
From your Jenkins dashboard, navigate to Manage Jenkins.
In the Security section, select Credentials.

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

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).

Select Create to complete your credential configuration.
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.
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
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 |
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.
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.
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 |
Check that the container is running:
docker ps --filter name=agent1
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.
agent1 on JenkinsFrom your Jenkins dashboard, navigate to Manage Jenkins.
Select Nodes.

Select New Node to create your agent.
Enter your Node name, select the Permanent Agent option, and select Create.
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.

Select Save and agent1 will be registered, but offline for the time being.
Select the agent1 node to view its status.
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.
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.
agent1From your Jenkins dashboard select New Item.
Enter a name, for example, First job on agent1.
Select Freestyle project and select OK to create the job.
Select the option Restrict where this project can be run.
Enter the node label (agent1) in the Label Expression field.

|
Be careful with white spaces before or after the label. |
Select the Execute shell option from the Build Steps dropdown;
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.

Select Save and then select Build Now.
Wait a few seconds, and then go to Console Output page. You should receive output similar to:

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.