--- title: "How to Set Up a New Jenkins Build Agent" description: "Add an additional Jenkins Agent Windows node to scale build job capacity and further automate your build environment!" canonical: "https://adamtheautomator.com/jenkins-agent/" --- # How to Set Up a New Jenkins Build Agent > Add an additional Jenkins Agent Windows node to scale build job capacity and further automate your build environment! Source: https://adamtheautomator.com/jenkins-agent/ --- ATA Learning Tap to hide [ ATA Learning ](/) * [Home](/) * [Tutorials](/tutorials/) * [Instructors](/author/) * [Advertising](/advertising/) * [Recommended Resources](/resources/) * [About Adam](/about-adam/) Search for: * [](https://twitter.com/adbertram) * [](https://github.com/Adam-the-Automator) * [](https://www.linkedin.com/company/adam-the-automator-llc) * [](/feed/) ![How to Set Up a New Jenkins Build Agent](https://adamtheautomator.com/wp-content/uploads/2021/03/How-to-Set-Up-a-New-Jenkins-Build-Agent.jpg) # How to Set Up a New Jenkins Build Agent [![](https://secure.gravatar.com/avatar/d0b9d42e21e5622713f8b693aa5c0f9244d5f7dd200ed29b8398f52dee5de337?s=192&d=mm&r=g)Adam Bertram](https://adamtheautomator.com/author/adam-bertram/)16 March 20214 min. read Categories: [DevOps](/category/devops/) Tags:[Jenkins](/tag/jenkins/) Table of Contents * [Prerequisites](#h-prerequisites) * [What are Jenkins Agents and the Jenkins Agent Controller?](#h-what-are-jenkins-agents-and-the-jenkins-agent-controller) * [Preventing the Controller Master Node from Running Jobs](#h-preventing-the-controller-master-node-from-running-jobs) * [Setting the TCP Port for Inbound Agents](#h-setting-the-tcp-port-for-inbound-agents) * [Create a New Jenkins Agent Node on the Jenkins Controller](#h-create-a-new-jenkins-agent-node-on-the-jenkins-controller) * [Next Steps](#h-next-steps) Are you running out of [Jenkins](https://www.jenkins.io/) executors or stuck waiting for queued jobs for your Jenkins Windows jobs? If so, you need to set up more [Jenkins agents](https://www.jenkins.io/doc/book/using/using-agents/). Not a reader? Watch this related video tutorial! **_Not seeing the video? Make sure your ad blocker is disabled._** In this tutorial, you’ll learn how to add a Jenkins agent Windows node to support an ever-growing resource need in your software build environment! ## Prerequisites To follow along with this article, you will need the following. * Working installation of a [Jenkins controller](https://www.jenkins.io/doc/book/installing/) installation equal to or greater than 2.176.1, and in this article, the controller is referred to as the master node. * Any supported Windows OS installation which will be referred to as the Jenkins agent node. ## What are Jenkins Agents and the Jenkins Agent Controller? A core component of Jenkins is the job. Jobs are instances of build automation that run a defined set of tasks. Supporting different job configurations requires an automation system to distribute build jobs among different nodes, which is simply an environment containing a Jenkins agent or controller. Jenkins agents run on a variety of different environments such as physical machines, virtual machines, [Kubernetes clusters](https://www.jenkins.io/doc/book/installing/kubernetes/), and [Docker images](https://www.jenkins.io/doc/book/installing/docker/). A Jenkins agent is an executable, residing on a node, that is tasked by the controller to run a job. Managing the different Jenkins agents is the job of the agent controller, also known as the master node. In a single Jenkins node configuration, the controller, can also act as both a Jenkin agent and run build jobs. As environments become more complex, this configuration becomes limiting. ## Preventing the Controller Master Node from Running Jobs Before you can add an additional Jenkins agent, you must first remove the master node from the build agent pool. Removing the master node from this pool ensures that the controller has adequate resources to coordinate build jobs. Below you will walk through the necessary settings to prevent the master node from running a job. 1. Navigate to the Jenkins user interface via a browser. In this tutorial, the Jenkins Controller uses the `192.168.x.x:8080` address. ![Logging into the Jenkins Dashboard.](https://adamtheautomator.com/wp-content/uploads/2021/03/Untitled-2021-03-09T154400.727-1.png) Logging into the Jenkins Dashboard. 2\. Once the Jenkins Dashboard appears, click the **Manage Jenkins** link. ![Navigate to Manage Jenkins.](https://adamtheautomator.com/wp-content/uploads/2021/03/Untitled-2021-03-09T154527.239.png) Navigate to Manage Jenkins. 3\. Next, click the **Configure System** link from within the **System Configuration** section. ![Navigate to Configure System.](https://adamtheautomator.com/wp-content/uploads/2021/03/Untitled-2021-03-09T154617.325.png) Navigate to Configure System. 4\. Scroll down the page to locate the setting, **\# of executors**, and set the value to `0`. This setting forces the master node, or controller, not to run any build jobs. ![Set the # of executors option to 0.](https://adamtheautomator.com/wp-content/uploads/2021/03/Untitled-2021-03-09T154721.737.png) Set the # of executors option to `0`. 5\. On the same page, locate the **Jenkins URL**. Change the URL to the IP address and port as used in the browser, instead of `localhost:8080`. > _An agent node may attempt to use `localhost` instead of the proper IP when communicating to the controller, if incorrectly set. With the proper IP address configured, you can avoid future agent communication problems!_ ![Update the Jenkins URL to the proper IP address.](https://adamtheautomator.com/wp-content/uploads/2021/03/Untitled-2021-03-09T154903.094.png) Update the Jenkins URL to the proper IP address. 6\. Click **Save** to confirm and apply the updated settings. ## Setting the TCP Port for Inbound Agents To inform Windows Jenkins Agent nodes how best to launch the job service and communicate back to the controller, you must configure the TCP inbound port settings. Defining the TCP inbound port settings ensures that the Jenkins agent knows how to connect to the Jenkins controller via the network. 1. Once again, navigate to the **Manage Jenkins** configuration page from the Jenkins dashboard. 2\. As shown below, click on the **Configure Global Security** section to locate the TCP port options. ![Navigate to the Configure Global Security section.](https://adamtheautomator.com/wp-content/uploads/2021/03/Untitled-2021-03-09T155026.450.png) Navigate to the Configure Global Security section. 3\. Scroll down to locate the **Agents** section and the **TCP port for inbound agents**. Change the option from **Disable** to **Random**. With the random setting, Jenkins selects a random available port number and shares that port number with an agent during their initial connection to the Jenkins HTTP port. ![Modify the TCP port for inbound agents setting to Random.](https://adamtheautomator.com/wp-content/uploads/2021/03/Untitled-2021-03-09T155111.302.png) Modify the TCP port for inbound agents setting to Random. 4\. Finally, click the **Save** button apply the updated setting. ## Create a New Jenkins Agent Node on the Jenkins Controller With all the appropriate settings configured, it is time to create your new Jenkins Agent node. Prior to this, create the working directory on the Windows node. On the Windows node, create the directory _C:\\Jenkins_. Once the working directory has been created, follow the below steps to configure your new node! 1. From the Jenkins dashboard, click the **Manage Nodes and Clouds** link. ![Navigate to Manage Nodes and Clouds.](https://adamtheautomator.com/wp-content/uploads/2021/03/Untitled-2021-03-09T155551.361.png) Navigate to Manage Nodes and Clouds. 2\. Click the **New Node** link on the left-hand menu. With only the controller as an agent, the Nodes list will only show the master node at first. ![Add a New Node to Jenkins.](https://adamtheautomator.com/wp-content/uploads/2021/03/Untitled-2021-03-09T155640.584.png) Add a New Node to Jenkins. 3\. Enter a **Node name**, which is `MyWindowsAgent1` for this tutorial but you may use a more appropriate identifier for your environment, and select the option for **Permanent Agent.** With additional agents, you may see a **Copy Existing Node** option as well. Finally, click the **Ok** button. ![Enter the node name and type.](https://adamtheautomator.com/wp-content/uploads/2021/03/Untitled-2021-03-09T155728.863.png) Enter the node name and type. 4\. Configure the new agent with the below settings. The green highlighted options are defaults. * **\# of executors**: Typically corresponds to the # of agent cores. A handy PowerShell snippet to find just that is below. ```powershell Get-CimInstance -ClassName Win32_Processor | Select-Object -Property Number* ``` * **Remote Work Directory**: _C:\\Jenkins_ * **Launch method**: Launch agent by connecting it to the master. ![Configure the new Jenkins Agent node. ](https://adamtheautomator.com/wp-content/uploads/2021/03/Untitled-2021-03-09T155914.620.png) Configure the new Jenkins Agent node. > _In a recent [solutions article](https://support.cloudbees.com/hc/en-us/articles/360029791092-Why-is-the-option-Launch-agent-by-connecting-it-to-the-master-not-available?page=19) from_ Cloudbees.com_, the agent launch options have changed in versions after 2.176.1. The “**Launch agent via Web Start**” is now “**Launch agent by connecting to the master**”._ 5\. Click the **Save** button and navigate to the Node list screen where the new Windows Jenkins Agent node will be shown. 6\. Click on the name of the new node, `MyWindowsAgent1` to retrieve the Agent installation links. ![Navigate to the new Windows node.](https://adamtheautomator.com/wp-content/uploads/2021/03/Untitled-2021-03-09T160035.594.png) Navigate to the new Windows node. 7\. Now open a remote desktop (RDP) connection to the Windows node where the Jenkins agent will be hosted. 8\. Navigate to `http://controllerip:port/computer/nodename`, via a browser, on the soon-to-be Windows agent. 9\. Click on the **Launch** button to download the agent installer and begin the [Jenkins agent installation](https://www.jenkins.io/blog/2020/09/12/new-jenkins-release-observations/#download-the-agent). ![Utilize the instructions and links to install the agent.](https://adamtheautomator.com/wp-content/uploads/2021/03/Untitled-2021-03-09T160151.291.png) Utilize the instructions and links to install the agent. ## Next Steps There are many ways to utilize your new-found agents. Between running [PowerShell scripts in Jenkins](https://adamtheautomator.com/jenkins-powershell/) to running [Jenkins in Docker](https://adamtheautomator.com/jenkins-docker/) you will find that there are many ways to automate your build environment! Share this article [Share on X](https://twitter.com/intent/tweet?url=https%3A%2F%2Fadamtheautomator.com%2Fjenkins-agent%2F&text=How%20to%20Set%20Up%20a%20New%20Jenkins%20Build%20Agent)[Share on Facebook](https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fadamtheautomator.com%2Fjenkins-agent%2F)[Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fadamtheautomator.com%2Fjenkins-agent%2F) ## Related Posts ![](https://adamtheautomator.com/wp-content/uploads/2022/05/Focused-Job-Configuration-with-the-Jenkins-DSL-Plugin.jpg) ### [Focused Job Configuration with the Jenkins DSL Plugin](/jenkins-dsl/) Learn the fundamentals of using the Jenkins DSL plugin to craft infrastructure as code and generate focused Jenkins jobs! ![](https://adamtheautomator.com/wp-content/uploads/2021/12/How-to-Create-a-Jenkins-CI-CD-Pipeline.jpg) ### [How to Create a Jenkins CI CD Pipeline](/jenkins-ci-cd/) Learn how to implement a Jenkins CI CD pipeline to significantly improve and automate your software development process! ![](https://adamtheautomator.com/wp-content/uploads/2021/11/Create-a-Jenkins-Build-Job-to-Automate-Web-Deployments.jpg) ### [Create a Jenkins Build Job to Automate Web Deployments](/jenkins-build-job/) Tired of manual deployment each time you update your code? Learn how to automate deployments by creating Jenkins build job in this step-by-step tutorial! ## Categories * [IT Ops](/category/it-ops/) * [Cloud](/category/cloud/) * [DevOps](/category/devops/) * [Home Ops](/category/home-ops/) * [Information Security](/category/infosec/) * [Software Development](/category/software-development/) ## Site * [Home](/) * [Tutorials](/tutorials/) * [Instructors](/author/) * [Advertising](/advertising/) * [Recommended Resources](/resources/) * [About Adam](/about-adam/) Copyright 2026© ATA Learning | [Privacy Policy](/privacy/)