Install new TeamCity build agent on Windows

TeamCity is an awesome tool that can be used to build a lot of different variety of projects. In its free version, it comes with a maximum of 100 build configurations and 3 configurable build agents (note that these values have been considerably increased quite recently as before it was only 20 build configurations and 1 build agent).

Recently, I had to setup a new build agent to be able to execute coded UI unit testing, however, it took me quite some time to figure out how to install an additional build agent on Windows as some crucial steps are missing from the TeamCity documentation. Basically, the symptom was that every time I installed a new build agent, the previously installed got overridden by the new one and at the end of the day, it was impossible to have more than one build agent at the same time.

This issue comes from the fact that the configuration of the windows service needs to be adapted before ending the installation of the new build agent (in a very not obvious way…). Here are the different steps to follow in order to do so:

Start by logging on your TeamCity administration interface and go in the “Administration” panel. There should be a link called “Install Build Agents” on which you must click to display a menu asking you how you want to install the agent. Select “MSI Windows Installer” to start the download of the installer.


Once the download is done, open the file and follow the step until this one:


Here, you can define where you want to place the files for your new build agent. Most of the time, you’ll want to install it in the root directory of your TeamCity installation even though you can install it wherever you want. Here, I’ll install it in a folder called “buildagent3” (as I already have 2 build agents) located next to the default one (“buildagent” in the root directory of the TeamCity installation). Click on “Next” and wait for the service to be installed.

The following window should appear once the file copy is done:


Enter the URL of TeamCity in “serverUrl” and a name and a port in the corresponding field. Beware that the name and the port must be unique. At this stage, you MUST NOT click on “Save” or your existing build agent would be overridden by the new one. Before confirming this screen, you need to go in \launcher\conf, open the file “wrapper.conf” and update the following properties:

  • wrapper.console.title: This is the title displayed when running the service in a console.
  • This is the name of the windows service.
  • wrapper.ntservice.displayname: This is the title of the windows service.
  • wrapper.ntservice.description: This is the description of the windows service.

So at the end of the day, the file should contain something like this:

# Wrapper Windows Properties
# Title to use when running as a console
wrapper.console.title=TeamCity Build Agent 03

# Wrapper Windows NT/2000/XP Service Properties
# WARNING – Do not modify any of these properties when an application
# using this configuration file has been installed as a service.
# Please uninstall the service before modifying this section. The
# service can then be reinstalled.

# Name of the service

# Display name of the service
wrapper.ntservice.displayname=TeamCity Build Agent 03

# Description of the service
wrapper.ntservice.description=TeamCity Build Agent Service 03

You can now save the file, come back to the build agent installation and click on “Save”. The next step is up to you but for this article, I’ll assume that you want to run the agent as a windows service:


Then, enter the credentials of the account used to run the service, click on “Next” and finish the installation by specifying that you want to start the service now.

You can confirm that the build agent is correctly installed by checking the list of installed windows service:


As you can see, I have installed 3 build agents on my server and they each have a specific windows service associated (the new one is not yet started but is about to be).

Note that it takes a certain time for TeamCity to consider the new agent as active. During this period of time, you’ll probably see it in the “Disconnected” tab of the “Agents” page of TeamCity. If you don’t want to wait for TeamCity to do the job, you can restart your machine (I notice that it was sometimes faster).


Note that, if like me, you tried to install a new agent like a cow boy, you probably messed up the default one of TeamCity. You can either do like me and uninstall all additional build agents, delete the folder of the default one (\buildAgent) then reinstall all the build agents like described above or you can follow the instructions in the “wrapper.conf” and reinstall the service manually. While I have no doubt that the second option would work, I can confirm that the first one also does.


2 Responses

  1. I cannot believe that this is not built into the installer … I wiped out the default agent twice before going off and finding your blog post thanks. 🙂 I also found that I had to manually add some rules to the firewall on the TC server in order to allow traffic off of the machine.
    (i was added an agent to a windows TC server for a linux TC server install use for build)

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.