Child pages
  • Step by step guide to set up master and agent machines on Windows

Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Note: There is no need to install Jenkins on the agent machine.

  1. On your master machine go to Manage Jenkins > Manage Nodes.

  2. New Node
    1. Enter Node Name
    2. Select Permanent Agent 
    3. Press OK.

  3. Fill out the following:
    1. Set a number of executors 
      1. (one or more) as needed.
    2. Set a Remote FS Root
      1. a home directory for the master on the agent machine.
      2. For a Windows agent, use something like: "C:\Jenkins\"
    3. Select the appropriate Usage setting:
      1. For an additional worker: Utilize this node as much as possible
      2. For specialized jobs: Leave this machine for tied jobs only
    4. Launch Method:
      1. An easy way to control a Windows agent is by using Launch agent via Java Web Start  (Recommended for Windows)
      2. TODO: add steps for other methods.
    5. Availability 
      1. Keep this agent online as much as possible
      2. TODO: add details for each option.
    6. Press OK.
  4. Now you need to connect your agent machine to the master using the following steps. 
    1. Open a browser on the agent machine and go to the Jenkins master server url (http://yourjenkinsmaster:8080).
    2. Go to Manage Jenkins > Manage Nodes
      1. Click on the newly created agent machine. You will need to login as someone that has the "Connect" Agent permission if you have configured global security.
    3. Click on the Launch button to launch agent from browser on agent.
    4. Run the program.

      If Windows asks you to choose a program, use $JAVA_HOME\bin\javaws.exe (the Java Web Start Launcher).
    5. If you encounter connection issue, then you could enlarge the popup windows to see the master port used and check your network configuration (firewall, port forward, ...). 

      Note that Jenkins chooses a random, high-number port. If you want Jenkins to use a static port, go to "Manage Jenkins" > "Configure Global Security" and choose the port number in the "TCP port for JNLP agents" box.
    6. If the port is open, the agent still can't connect, and your Jenkins instance is served securely over SSL/HTTPS, download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 8. Take the .jar files and save them to $JAVA_HOME\lib\security. Try the above steps again.
    7. Now you should see the agent machine connected under Nodes.


  1.  If you want the service to run on start-up of the agent machine do the following (Windows only directions):
    1. In the agent program running on your agent machine, 
    2. click File --> Install as Windows Service. 

      Note that this feature requires ".Net Framework 3.5"
    3. Start, type Services and Select the Services program.
    4. Find Jenkins Agent in the list, Double click to open.
    5. Select Startup type --> Automatic.
    6. Go to the Log On tab, change the Log on as to a user of your choice (Special user account Jenkins recommended).
    7. Make sure that auto login is set for the agent machine for the user account, then the VM (or physical computer) should connect and be available when needed.

TODO: Add steps for connecting via ssh

Also: take a look at Distributed builds

  • No labels


  1. Unknown User (davida)

    Looking forward to this page being available. I am just getting started with a master/slave configuration and know nothing!

  2. Unknown User (johnbuilder)

    Waiting for this page to come and still looking for clues about the master/slave configuration.

  3. Unknown User (alexlombardi)

    I am trying to set up several slaves as windows services on one machine and then connecting them to a master on another windows server, and am getting nowhere with this. I can not find any documentation anywhere on what the process would be to do this. I have configured and added slaves on the same machine as my master, but that's obviously not what I want. Any help please?

    1. Unknown User (

      I'm probably too late for you, but maybe this will be helpful for other people who come here.

      Here is what has worked for me for most of my build projects.

      Log onto the machine that you want to set up as a slave. Connect to your server (http://servername:8080, replacing servername with the actual name of the server) and click on Manage Hudson. Click on Manage Nodes and then click on New Node. Give it a name and choose Dumb Slave and click OK (for future slaves you can just copy from existing). Fill in the fields, leaving settings at their defaults, and click Save.

      Now that it is created, you can click on it in the list of nodes. It should show a page that tells you how to launch the slave. Since you are already on the slave machine, you just need to click the Launch button. It will start up the slave under Java and will say it is connected if it all went well.

      Then you simply click on the File menu in that java window and choose Install as a Windows Service. It should then set up the service and shut down the slave agent you had just launched. From there, you don't really have much to do besides send builds to it.

      Like I said, this has worked for me with most of my build configurations, so I guess this could be considered the basic setup. In some cases, there is more that needs to be done but I am still fumbling through those situations and have nothing positive to report yet.

      1. Unknown User (gigapromoters)

        Awesome! Thanks.

  4. Unknown User (mital)

    Can I create slaves of different OSes. like I am working on a project which is ported to windows/linux/mac. I have setup separate Hudson CIs for the same. I was thinking If I can merge them into a single hudson.

    jobs particular to any OS should be given to that os's slave.

    I have found no documentation which can explain me Master/Slave Hudson properly.

    If this is not available / implemented currently with hudson.. this is one of the cool thing which would help lot of people who are developing cross-platform apps.

    Thanks :)

    1. Unknown User (davida)

      You can certainly create slaves on different o/s's. We have our Hudson master on Windows and we have Hudson slaves on Windows and Linux. Having set-up the slaves, you can assign them to a job by specifying their label in the 'Restrict where this project can be run' field of the project. So what you want is already possible.

      I would suggest you post your questions to Hudson user's mail list.


  5. Unknown User (welwitscha)

    I followed all the steps but I get all the time the follow  ERROR

    java.lang.Exception: The server rejected the connection: Unauthorized access

    at hudson.remoting.Engine.onConnectionRejected (


    What can I do ? 

    1. Unknown User (sarnlaugsson)

      At what point do you get the error? When trying to start the service on the slave?

    2. Unknown User (sb5565)

      I received the same error and it turned out the issue was that I had a local version of jenkins also running on the slave from earlier tests I was running.  When I shut it down on the remote server I was able to connect without an error.  Hope this helps. 

  6. Unknown User (welwitscha)

    It was coming when I launch the java web jlpn on slave  but I found out that the jenkins url on master was set as localhost:8080

    Setting the jenkins url in the correct way it solve the problem

  7. Unknown User (sb5565)

    I am also getting the error and it is occurring when I am launching the agent from the browser on the slave.

  8. Unknown User (akka88)


    I have installed jenkins on Ubuntu, and is running Ok on it.

    But when i followed the above setups for launching a slave agent on windows i am getting errors.

    The error actually starts when i click the "launch button" on starting it as slave on windows .

    when i click launch button, i could see the its trying to connect to master ( connection to "name of Ubuntu machine where master is running":55735 ) but after sometime i get error -

    " caused: due to java exception"

    Could anyone please suggest what is the issue?

    Is it that the connection to port 55735 is not open on Ubuntu to connect from my windows machine.

    Thanks in advance.

  9. Unknown User (yamoinca)

    I found this page confusing. It's not clear that you are setting up a slave on the slave machine. I thought it was starting off by setting up slave information on a master node (I think another commenter above implies he went down that route as well). Even the field "Remote FS root" seems a misnomer, since it is actually a "local FS root", no?

    The restriction that the slave can't have a jenkins job running seems restrictive. My available build machines all have jenkins jobs running that I cannot all shutdown while I test/experiment with a master/slave configuration. Is there any way around this restriction?

  10. Unknown User (ngealy)

    Problem: Mac OS X slave kept connecting for a few seconds and then terminating when using the JNLP agent.

    Solution: Whatever you choose as "Remote FS Root" location must exist on the slave, and the user that launches the JNLP agent must have full access to that directory.

  11. Unknown User (dallysoft)


    I want to automate the iOS app build in my mac from a windows machine.

    Jenkin run in my windows machine. I have a mac slave. Mac slave have different users and 'jenkin' is one of them.

    I am building the project in a shell script  

    I was able to run such config using ssh (run slave machine as unix ssh). I had to give a jvm configuration -Djava.awt.headless=true in the node ssh configuration.

    Now I want to upload the build artifacts to a server only accessible from windows master. Where to write those bat commands? If I write in post build steps then the batch command tries to run in the slave not in the master. How to tell jenkins  to take the build artifacts from slave, and run some command  (copy files) in the master machine.

  12. Unknown User (acordinz)


    This is my first time trying to setup a slave node, and I'm having problems.

    My master node is Ubuntu Server 11.04, and the slave is Window XP Pro SP3.

    I've followed this guide and after I push the launch button only the "java" window appears saying it is "Connected" but the "Install as Window service" never shows up, installation gets stuck for several hours trying to install "chromedriver" (see attached image).

    Can you help me, please. Thanks

  13. Unknown User (songwang)

    Expecting a page step by step set up *nix slave, Windows master.

  14. Unknown User (maximojo)

    Had a problem installing as a service on Windows 10. The problem was I followed the above steps but when I went to install as a service (at 6b) got a permissions error as it was launched through the browser (which I was not running as admin).

    That was because slave-agent.jnlp needs to be launched as an admin. Then you can use the option on the widget to install as a service with no problems. So either launch through an admin command-line and then add through the widget or (haven't tried this) launch browser as admin and then click the Launch link.

  15. Unknown User (3020722)

    Error occurred during initialization of VM
    Could not find agent library jvmhook on the library path, with error: %1 is not a valid Win32 application
    Picked up JAVA_TOOL_OPTIONS: -agentlib:jvmhook


    How to resolve this issue

  16. Unknown User (rag1)

    Hi every body, I always get following error on Windows slave side:

    Mai 17, 2018 2:13:13 PM hudson.remoting.jnlp.Main createEngine
    INFO: Setting up slave: windows-slave
    Mai 17, 2018 2:13:13 PM hudson.remoting.jnlp.Main$CuiListener <init>
    INFO: Jenkins agent is running in headless mode.
    Mai 17, 2018 2:13:13 PM org.jenkinsci.remoting.engine.WorkDirManager initializeWorkDir
    INFO: Using C:\Users\serviceuser\.jenkins\remoting as a remoting work directory
    Mai 17, 2018 2:13:13 PM hudson.remoting.jnlp.Main$CuiListener status
    INFO: Locating server among [https://hostname:port/jenkins/]
    Mai 17, 2018 2:13:13 PM hudson.remoting.jnlp.Main$CuiListener error
    SEVERE: https://hostname:port/jenkins/ is not Jenkins https://hostname:port/jenkins/ is not Jenkins
        at org.jenkinsci.remoting.engine.JnlpAgentEndpointResolver.resolve(
        at hudson.remoting.Engine.innerRun(

    I do not connect to the JNLP port (50000) I connect to the official https port.

    Do someone have idea what it could be? Thanks in advance.

  17. Unknown User (tarunkum)

    Am getting the following error in slave console logs, while launching slave:


    Connection was broken

  Socket closed
     at Method)
     at Source)
     at Source)
     at Source)
     at Source)
     at$PeekInputStream.peek(Unknown Source)
     at$BlockDataInputStream.peek(Unknown Source)
     at$BlockDataInputStream.peekByte(Unknown Source)
     at Source)
     at Source)
     at hudson.remoting.Command.readFrom(
     at hudson.remoting.SynchronousCommandTransport$
    Please guide on how to proceed further? slave is able to connect to master, but the above error is repeated intermittently.


  18. Unknown User (tsaibabu4u)

    It seems JNLP is disabled in a newer version of Jenkins and it is not recommended a way to connect to Windows slave. is this statement correct?

    I am seeing below warning "This Jenkins instance uses deprecated protocols: JNLP-connect,JNLP2-connect,JNLP3-connect. It may impact stability of the instance. If newer protocol versions are supported by all system components (agents, CLI and other clients), it is highly recommended to disable the deprecated protocols"

    Do you have any other recommended way to connect Windows slave?

  19. Unknown User (vloria88)

    I agree with previous posters, this is assuming that you  can connect the slave to a browser.  How would you do this if you are connecting to an AWS EC2 Linux instance as a slave?

  20. Unknown User (edgarcb)

    For step 3 - d:

     Launch method: (Launch agent via Java Web Start) ...

      That option does not even exist in version 2.150.2, can anybody confirm that you can actually use powershell on a slave (using ubunut/linux master). I followed this configuration plus what is here....Windows agents fail to start via DCOM and nothing works...

    1. Unknown User (adam_adam)

      I'm not sure about powershell, but I just ran it in a classic cmd terminal and it worked fine - 2.150.2, master is Linux (official docker version) . I had to download agent.jar to the slave first and put it in the same folder as slave-agent.jnlp, if that makes any difference. I think I may have had to run the command as a batch script as administrator too.

  21. Unknown User (theja0473)

    Hi All,

    I have Windows 10 machine as slave for Jenkins as per the doc mentioned if I configure there is a problem which I observe when network disconnection happens.

    The slave service is not restarting so that the slave will show as offline. we need to go to Jenkins Agent service on Windows and restart manually.

    Is there any auto fix for this mechanism?


    1) → Master and Slave configured successfully.

    2) → Network error occurred.

    3) → Network Fixed.

    4) → Slave will be offline in Master node page.

    5) → Need to logon to Slave Machine and "manually restart the Jenkins agent service"

    6) → Then Slave will be online.

    May I know Why is 5th step required Here it should bring up automatically as per configuration?

    Note: It is working in Win7 Slave machine.

    Thanks in Advance!

    Thejeswarareddy R