Introduction

Jenkins supports distributed builds by using agents (nodes). A Windows agent allows Jenkins to execute jobs on a Windows machine while the Jenkins controller manages the pipeline.

This guide explains how to connect a Windows machine as a Jenkins agent using the Launch agent by connecting it to the controller (Inbound Agent) method.

Prerequisites

  • Jenkins Controller installed and running
  • Windows 10/11 or Windows Server
  • Java 17 or later installed on Windows
  • Network connectivity between Windows machine and Jenkins server
  • Jenkins user account with permission to create/manage nodes

Step 1: Install Java on Windows

Verify Java installation:

java -version

Example:

openjdk version "17.0.15"

If Java is not installed, download and install OpenJDK or Oracle JDK.

Step 2: Create a New Node in Jenkins

  1. Login to Jenkins.
  2. Go to Manage Jenkins.
  3. Select Nodes.
  4. Click New Node.

Enter:

  • Node Name: windows-agent
  • Type: Permanent Agent

Click Create.

Step 3: Configure the Node

Configure the following settings.

Number of Executors

2

Remote Root Directory

C:\Jenkins

Create this folder on Windows if it does not exist.

Labels

windows

Usage

Use this node as much as possible

Launch Method

Select:

Launch agent by connecting it to the controller

Save the configuration.

Step 4: Obtain the Agent Command

Open the newly created node.

Jenkins displays a command similar to:

java -jar agent.jar ^
-url http://YOUR-JENKINS:8080/ ^
-secret YOUR_SECRET ^
-name "windows-agent" ^
-workDir "C:\Jenkins"

Step 5: Download agent.jar

Open:

http://YOUR-JENKINS:8080/jnlpJars/agent.jar

Download:

agent.jar

Copy it to:

C:\Jenkins

Step 6: Open Command Prompt

Navigate to the Jenkins directory:

cd C:\Jenkins

Run the agent:

java -jar agent.jar ^
-url http://YOUR-JENKINS:8080/ ^
-secret YOUR_SECRET ^
-name "windows-agent" ^
-workDir "C:\Jenkins"

If successful, you will see:

INFO: Connected
INFO: Agent successfully connected

The Jenkins dashboard will show the node as Online.

Step 7: Configure Firewall (If Needed)

Allow outbound access to the Jenkins server.

Default Jenkins port:

8080

If using HTTPS:

443

Verify connectivity:

ping YOUR-JENKINS

or

curl http://YOUR-JENKINS:8080

Running the Agent as a Windows Service

Instead of keeping Command Prompt open, install the Jenkins agent as a Windows Service.

From the node page, download the Windows Agent service package or use the Jenkins Agent Service installer.

Benefits:

  • Starts automatically after reboot
  • Runs in the background
  • No need to keep a command window open
  • Recommended for production

Troubleshooting

Java Not Found

Error:

'java' is not recognized

Solution:

  • Install Java.
  • Add the Java bin directory to the PATH environment variable.

Connection Refused

Error:

Connection refused

Check:

  • Jenkins is running.
  • Correct server URL.
  • Firewall allows access.
  • Port 8080 or 443 is reachable.

Invalid Secret

Error:

Unauthorized

Solution:

  • Copy the latest secret from the Jenkins node page.
  • Ensure the node name matches exactly.

Agent Goes Offline

Possible causes:

  • Network interruption
  • Firewall timeout
  • Java process stopped

Restart:

java -jar agent.jar ...

Or configure the agent as a Windows Service.

Verify Agent Status

On the Jenkins dashboard:

  • Online: Agent is connected and ready.
  • Offline: Agent is disconnected.
  • Temporarily Offline: Agent has been manually disabled.

Conclusion

Connecting a Windows node to Jenkins using an inbound agent is a straightforward way to distribute builds and run Windows-specific workloads such as .NET, PowerShell, or desktop application builds. By installing Java, creating a node in Jenkins, downloading agent.jar, and connecting with the provided command, you can quickly add Windows build capacity. For production environments, running the agent as a Windows Service ensures reliability and automatic startup after system reboots.

Post Views: 0

Leave a Reply