{"id":11005,"date":"2026-07-24T19:02:04","date_gmt":"2026-07-24T13:32:04","guid":{"rendered":"https:\/\/pheonixsolutions.com\/blog\/?p=10553"},"modified":"2026-08-25T15:00:31","modified_gmt":"2026-08-25T09:30:31","slug":"connect-windows-agent-to-jenkins","status":"publish","type":"post","link":"https:\/\/pheonixsolutions.com\/blog\/connect-windows-agent-to-jenkins\/","title":{"rendered":"How to Connect a Windows Node (Agent) to Jenkins: A Complete Guide"},"content":{"rendered":"\n<h3 class=\"wp-block-heading\">Introduction<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Jenkins supports distributed builds by using <strong>agents (nodes)<\/strong>. A Windows agent allows Jenkins to execute jobs on a Windows machine while the Jenkins controller manages the pipeline.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">This guide explains how to connect a Windows machine as a Jenkins agent using the <strong>Launch agent by connecting it to the controller (Inbound Agent)<\/strong> method.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Prerequisites<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Jenkins Controller installed and running<\/li>\n\n\n\n<li>Windows 10\/11 or Windows Server<\/li>\n\n\n\n<li>Java 17 or later installed on Windows<\/li>\n\n\n\n<li>Network connectivity between Windows machine and Jenkins server<\/li>\n\n\n\n<li>Jenkins user account with permission to create\/manage nodes<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">Step 1: Install Java on Windows<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Verify Java installation:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>java -version<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Example:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>openjdk version \"17.0.15\"<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">If Java is not installed, download and install OpenJDK or Oracle JDK.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Step 2: Create a New Node in Jenkins<\/h3>\n\n\n\n<ol start=\"1\" class=\"wp-block-list\">\n<li>Login to Jenkins.<\/li>\n\n\n\n<li>Go to <strong>Manage Jenkins<\/strong>.<\/li>\n\n\n\n<li>Select <strong>Nodes<\/strong>.<\/li>\n\n\n\n<li>Click <strong>New Node<\/strong>.<\/li>\n<\/ol>\n\n\n\n<p class=\"wp-block-paragraph\">Enter:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Node Name: <code>windows-agent<\/code><\/li>\n\n\n\n<li>Type: Permanent Agent<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">Click <strong>Create<\/strong>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Step 3: Configure the Node<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Configure the following settings.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">Number of Executors<\/h4>\n\n\n\n<pre class=\"wp-block-code\"><code>2<\/code><\/pre>\n\n\n\n<h4 class=\"wp-block-heading\">Remote Root Directory<\/h4>\n\n\n\n<pre class=\"wp-block-code\"><code>C:\\Jenkins<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Create this folder on Windows if it does not exist.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">Labels<\/h4>\n\n\n\n<pre class=\"wp-block-code\"><code>windows<\/code><\/pre>\n\n\n\n<h4 class=\"wp-block-heading\">Usage<\/h4>\n\n\n\n<pre class=\"wp-block-code\"><code>Use this node as much as possible<\/code><\/pre>\n\n\n\n<h4 class=\"wp-block-heading\">Launch Method<\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">Select:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Launch agent by connecting it to the controller<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Save the configuration.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Step 4: Obtain the Agent Command<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Open the newly created node.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Jenkins displays a command similar to:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>java -jar agent.jar ^\n-url http:\/\/YOUR-JENKINS:8080\/ ^\n-secret YOUR_SECRET ^\n-name \"windows-agent\" ^\n-workDir \"C:\\Jenkins\"<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">Step 5: Download agent.jar<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Open:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>http:&#47;&#47;YOUR-JENKINS:8080\/jnlpJars\/agent.jar<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Download:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>agent.jar<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Copy it to:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>C:\\Jenkins<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">Step 6: Open Command Prompt<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Navigate to the Jenkins directory:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>cd C:\\Jenkins<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Run the agent:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>java -jar agent.jar ^\n-url http:\/\/YOUR-JENKINS:8080\/ ^\n-secret YOUR_SECRET ^\n-name \"windows-agent\" ^\n-workDir \"C:\\Jenkins\"<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">If successful, you will see:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>INFO: Connected\nINFO: Agent successfully connected<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">The Jenkins dashboard will show the node as <strong>Online<\/strong>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Step 7: Configure Firewall (If Needed)<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Allow outbound access to the Jenkins server.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Default Jenkins port:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>8080<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">If using HTTPS:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>443<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Verify connectivity:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>ping YOUR-JENKINS<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">or<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>curl http:\/\/YOUR-JENKINS:8080<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">Running the Agent as a Windows Service<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Instead of keeping Command Prompt open, install the Jenkins agent as a Windows Service.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">From the node page, download the Windows Agent service package or use the Jenkins Agent Service installer.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Benefits:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Starts automatically after reboot<\/li>\n\n\n\n<li>Runs in the background<\/li>\n\n\n\n<li>No need to keep a command window open<\/li>\n\n\n\n<li>Recommended for production<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">Troubleshooting<\/h3>\n\n\n\n<h4 class=\"wp-block-heading\">Java Not Found<\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">Error:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>'java' is not recognized<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Solution:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Install Java.<\/li>\n\n\n\n<li>Add the Java <code>bin<\/code> directory to the <code>PATH<\/code> environment variable.<\/li>\n<\/ul>\n\n\n\n<h4 class=\"wp-block-heading\">Connection Refused<\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">Error:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Connection refused<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Check:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Jenkins is running.<\/li>\n\n\n\n<li>Correct server URL.<\/li>\n\n\n\n<li>Firewall allows access.<\/li>\n\n\n\n<li>Port 8080 or 443 is reachable.<\/li>\n<\/ul>\n\n\n\n<h4 class=\"wp-block-heading\">Invalid Secret<\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">Error:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Unauthorized<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Solution:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Copy the latest secret from the Jenkins node page.<\/li>\n\n\n\n<li>Ensure the node name matches exactly.<\/li>\n<\/ul>\n\n\n\n<h4 class=\"wp-block-heading\">Agent Goes Offline<\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">Possible causes:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Network interruption<\/li>\n\n\n\n<li>Firewall timeout<\/li>\n\n\n\n<li>Java process stopped<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">Restart:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>java -jar agent.jar ...<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Or configure the agent as a Windows Service.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">Verify Agent Status<\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">On the Jenkins dashboard:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Online<\/strong>: Agent is connected and ready.<\/li>\n\n\n\n<li><strong>Offline<\/strong>: Agent is disconnected.<\/li>\n\n\n\n<li><strong>Temporarily Offline<\/strong>: Agent has been manually disabled.<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">Conclusion<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">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 <code>agent.jar<\/code>, 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.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Introduction Jenkins supports distributed builds by using agents (nodes). A Windows agent allows Jenkins to execute jobs on a Windows [&hellip;]<\/p>\n","protected":false},"author":532,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"default","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","ast-disable-related-posts":"","theme-transparent-header-meta":"","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"default","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_feature_clip_id":0,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":false,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2},"jetpack_post_was_ever_published":false},"categories":[1019,1051],"tags":[],"class_list":["post-11005","post","type-post","status-publish","format-standard","hentry","category-cloud-aws","category-jenkins","psol-cat-cloud-aws"],"jetpack_publicize_connections":[],"jetpack_shortlink":"https:\/\/wp.me\/phn2x7-2Rv","jetpack_sharing_enabled":true,"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/pheonixsolutions.com\/blog\/wp-json\/wp\/v2\/posts\/11005","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/pheonixsolutions.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/pheonixsolutions.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/pheonixsolutions.com\/blog\/wp-json\/wp\/v2\/users\/532"}],"replies":[{"embeddable":true,"href":"https:\/\/pheonixsolutions.com\/blog\/wp-json\/wp\/v2\/comments?post=11005"}],"version-history":[{"count":2,"href":"https:\/\/pheonixsolutions.com\/blog\/wp-json\/wp\/v2\/posts\/11005\/revisions"}],"predecessor-version":[{"id":11050,"href":"https:\/\/pheonixsolutions.com\/blog\/wp-json\/wp\/v2\/posts\/11005\/revisions\/11050"}],"wp:attachment":[{"href":"https:\/\/pheonixsolutions.com\/blog\/wp-json\/wp\/v2\/media?parent=11005"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/pheonixsolutions.com\/blog\/wp-json\/wp\/v2\/categories?post=11005"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/pheonixsolutions.com\/blog\/wp-json\/wp\/v2\/tags?post=11005"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}