Jenkins Home Lab: Part 3 - Setting up Windows Agents

Jenkins Home Lab

A guide for building a complete Jenkins home lab

Today, since we already have a working setup of Jenkins, lets expand it to include windows agents.

Configuring Jenkins

There are a few things that need to be configured on the Jenkins master server, we’ll get that out of the way first.

Enable TCP ports for JNLP usage

This is likely already done if you are running the Docker image for the master server, but you should check anyway. This will enable the java client on windows to communicate with the master server.

Go to the home page and click on Manage Jenkins


Click on Configure Global Security


Scroll down to Agents and set the TCP port for inbound agents to 50000.


Install the Powershell plugin

Powershell gives you significantly more flexibility in build steps. This plugin will add support for Powershell commands as a build step.

Go to the home page and click on Manage Jenkins


Click on Manage Plugins


Click on Available and search for “Powershell”. Tick this plugin and click install without restart.


Create agent node

Go to the home page and click on Manage Jenkins


Click on Manage nodes


Enter a name and choose Permanent Agent


Enter the following details:

  • Name: Name of the node to be displayed in Jenkins
  • # of executors: how many jobs should be able to concurrently run on this agent, generally set this to the number of cores available.
  • Labels: a list of labels associated with this node. This can be used to restrict jobs to this node or node type. I like to put in operating system and architecture.
  • Remote root directory: C:\jenkins
  • Launch method: Launch agent by connecting it to the master


After clicking on save you will be returned to a list of nodes. Click on the newly created node which will be offline.


Depending on which master hosting method used you may be able to launch with Java webstart, but that won’t allow you to install the service since it won’t run with administrative priviledges. Instead we’ll use the second connection method. For now copy the following as we will use them a little later:


Configure Windows System

Now we can configure the windows system itself. We need to install some prerequisites and then install the agent as a service.

Install the .NET Framework

In an administrative Powershell run the command below to install the .NET Framework

Add-WindowsCapability -Online -Name NetFx3~~~~

Install Java

The agent needs a Java JRE installed. You can download it from here:

If you use chocolatey package manager you can run the following command.

choco install javaruntime

Licensing Note Oracle Java needs to be licensed for business use. Check your licensing is appropriate.

Setup Agent

There are a few ways to setup this agent to run on startup. I’ll show 2 methods. The first will work if you used the Docker method for creating the master server. If you installed the master using the ubuntu/RPi method then most likely you’ll need to use the second method.

Security Note Both of these methods will have the installed service run as the local SYSTEM user which grants it full administrative rights on the PC. In a production environment you will want to run the agent as a domain user. This can be configured through the normal Windows Service Management. Instructions can be found under the Configure Slave Service to Run as Domain User section of the documentation here

Jump to the instructions for your method:

Docker hosted master method

From the Windows agent system log in to Jenkins and go to the status page for the windows node that was created earlier.


Click the Launch agent from browser. This will start an agent with a GUI. Click File and then “Install as a Service”. This will fail but will download the files we need.


Open an administrative shell and enter the following commands to install the service.

cd c:\jenkins
.\jenkins-slave.exe install
net start jenkinsslave-c__jenkins

This will start the agent and it will relaunch every reboot. You can skip ahead to setting up a test job.

Ubuntu/Raspbian hosted master method

I adapted this method from a larger method on stackoverflow. From the Windows agent system log in to Jenkins and go to the status page for the windows node that was created earlier.


Create a folder, c:\jenkins

Download agent.jar (the link specified on the agent page) to c:\jenkins

Create a batch file with the command under “Run from agent command line” which will look like below. Save this as JenkinsService.bat

java -jar agent.jar -jnlpUrl http://HOSTNAME:8080/computer/windows-agent-1/slave-agent.jnlp -secret SECRETKEY -workDir  "c:\jenkins"

Install NSSM, either manually or through chocolatey.

choco install nssm

In an administrative shell run the following to register this agent.

nssm install JenkinsAgent C:\jenkins\JenkinsService.bat
nssm start JenkinsAgent

This will start the agent and it will relaunch every reboot.

Create a test job for Windows agents

From the Jenkins homepage click “New Item”.


Enter the name as Windows-Agent-Test, select Freestyle Project and click save.


In the details for this job enable “Restrict where to run this job” and type the label “windows”. This will mean it will only run on the agent we just created.


We want to add 2 build steps. First add a Batch command and type the following command to print all environment variables.


Now add a Powershell build step and add the following command. This will print various information about the system.



Click save and this will return you to the status page for the job. Click “Build Now” and wait a few seconds for the job to run.


Once you see the job has turned blue in the bottom left you can click #1 and then click “Console Output” to see what was printed out.



What’s next?

We now have a fairly robust lab for working with any kind of job, however managing agents can be kind of annoying, and there is always potential for dependencies to be installed on them which are not documented, or older versions conflicting with newer builds. We can solve these types of issues by dynamically creating agents and installing dependencies as needed. Tomorrow we’ll setup a linux docker host and setup on-demand agents.

jenkins ci homelab sysadmin windows