You are viewing the documentation of TeamCity 2018.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.


Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


Before you can start customizing projects and creating build configurations, you need to configure build agents. Please review the agent-server communication and Prerequisites section before proceeding with agent installation. 


titleLegacy bidirectional communication notes

By default unidirectional agent-to-server connection via polling protocol is used by TeamCity.

If you need to use legacy bidirectional communication (not recommended), in addition for the agent to server connections, the server must be able to open HTTP connections to the agent. The agent port is determined using the ownPort property of the buildAgent.properties file as the starting port (9090 by default, next port is used if the specified port is busy), and the following IP addresses are tried:

  • the address specified in the ownAddress property of the buildAgent.properties file (if any)
  • the source IP of the HTTP request received by the server when the agent establishes a connection to the server. If a proxying server is used, it must be correctly configured.
  • the addresses of the network interfaces on the agent machine

If the agent is behind NAT and cannot be accessed by any of addresses of the agent machine network interfaces, please specify the ownAddress property in the buildAgent.properties file.

Please ensure that any firewalls installed on the agent, server machine, or in the network and network configuration comply with these requirements.


  • be able to open outbound HTTP connections to the server address (the same address you use in the browser to view the TeamCity UI, configured in buildAgent.properties file)
  • have full permissions (read/write/delete) to the following directories recursively: <agent home> (necessary for automatic agent upgrade and agent tools support), <agent work>, <agent temp>, and agent system directory (set by workDir, tempDir and systemDir parameters in buildAgent.properties file)
  • be able to launch processes (to run builds).
  • be able to launch nested processes with the following parent process exit (this is used during agent upgrade)


  • Log on as a service (to run as Windows service)
  • Start/Stop service (to run as Windows service, necessary for the agent upgrade to work, see also Microsoft KB article)
  • Debug programs (required for take process dump functionality to work)
  • Reboot the machine (for required for agent reboot functionality to work

  • To be able to monitor performance of a build agent run as a Windows service, the user starting the agent must be a member of the Performance Monitor Users group


  • the user must be able to run the shutdown command (for the agent machine reboot functionality and the machine shutdown functionality when running in a cloud environment)
  • when using systemd, it should not kill the processes on the main process exit (use RemainAfterExit=yes)

Build-related Permissions


A TeamCity agent connects to the TeamCity server via the URL configured as the "serverUrl" agent property. This is called unidirectional agent-to-server connection. If specifically configured, TeamCity agent can use legacy bidirectional communication which also requires establishing a connection from the server to the agents.
Unless security in transfer between the agent and the server is important, it is recommended to deploy agents and the server into a secure environment and configure agents to use plain HTTP URL for the server as this reduces transfer overhead.To view whether the agent-server communication is unidirectional or bidirectional for a particular agent, navigate to Agents | <Agent Name> | Agent Summary tab, the Details section, Communication Protocol.


Agents use unidirectional agent-to-server connection via the polling protocol: the agent establishes an HTTP(S) connection to the TeamCity Server, and polls the server periodically for server commands.

HTTPS agent-server connection

It is possible and recommended to set up a server to be available via the HTTPS protocol, so all the use HTTPS for agent to server communications (check related server configuration notes). If the agents and the server are deployed into a secure environment, agents can be configured to use plain HTTP URL for connections to the server as this reduces transfer overhead. Note that the data travelling through the connections connection established from an agent to the server (including the download of build includes build settings, repository access credentials and keys, repository sources, build artifacts, build progress messages and build log) can be secured. See Using HTTPS to access TeamCity server for configuration details.. In case of using http:// protocol that data can be compromised via "man in the middle attack".



The bidirectional communication is a legacy connection between the agent and the server and it needs to be specifically enabled (see below). When enabled, it requires the agent to connect to the server via HTTP (or HTTPS) and the server to connect to the agent via HTTP.


  1. Install a build agent using any of the following options:
  2. After installation, configure the agent specifying its name and the address of the TeamCity server in the conf/buildAgent.properties file.
  3. Start the agent. If the agent does not seem to run correctly, please check the agent logs.


  1. In the TeamCity Web UI, navigate to the Agents tab.
  2. Click the Install Build Agents link and select MS Windows Installer to download the installer.
  3. Run On the agent, run the agentInstaller.exe Windows Installer and follow the installation instructions.


    Please ensure that the user account used to run the agent service has appropriate permissions

Installing via Docker Agent Image


Installing via ZIP File

  1. Make sure a JDK (JRE) 1.8.0_161 or later (Java 6-10 are supported, but 8 but 1.8.0_161+ is recommended)is properly installed on the agent computer.
  2. On the agent computer, make sure the JRE_HOME or JAVA_HOME environment variables are set (pointing to the installed JRE or JDK directory respectively).
  3. In the TeamCity Web UI, navigate to the Agents tab.
  4. Click the Install Build Agents link and select Zip file distribution to download the archive.
  5. Unzip the downloaded file into the desired directory.
  6. Navigate to the <installation path>\conf directory, locate the file called buildAgent.dist.properties and rename it to buildAgent.properties.
  7. Edit the buildAgent.properties file to specify the TeamCity server URL (usage of https:// is recommended, see the notes) and the name of the agent. Please refer to Build Agent Configuration section for details on agent configuration.
  8. Under Linux, you may need to give execution permissions to the bin/agent.sh shell script.


    On Windows you may also want to install the build agent windows service instead of the manual agent startup.





  1. Installed JDK(JRE) 6-10 (8 is recommended1.8.0_161 or later is recommended). The JVM should be reachable with the JAVA_HOME(JRE_HOME) global environment variable or be in the global path (i.e. not in user's .bashrc file, etc.)
  2. The unzip utility.
  3. Either wget or curl.


  1. Installed JDK/JRE 6-10 (8 is recommended1.8.0_161 or later is recommended).

    Wiki Markup
    {hidden-data}recommended. No preinstalled JRE required. Zipped JRE will be downloaded from the TeamCity server during the installation phase (there is no JRE's zip bundled to TC Server now, you have to put "agent-jre-win32.zip" archive under "TEAMCITY_SERVER_ROOT/webapps/ROOT/update" folder). {hidden-data}

  2. Sysinternals psexec.exe on the TeamCity server. It has to be accessible in paths. You can install it using Administration | Tools page.
    Note that PsExec applies additional requirements to a remote Windows host (for example, administrative share on remote host must be accessible). Read more about PsExec.


To configure the agent to be started automatically, see the corresponding sections:
Linux : configure daemon process with agent.sh start command to start it and agent.sh stop command to stop it.




To run agent automatically on the machine boot under Windows, you can either set up the agent to be run as a Windows service or use another way of the automatic process start.
Using the Windows service approach is the easiest way, but Windows applies some constraints to the processes run this way.
A TeamCity agent works reliably under Windows service provided all the requirements are met, but is often not the case for the build processes configured to be run on the agent.


titleService system account

To run builds, the build agent must be started under a user with sufficient permissions for performing a build and managing the service. By default, a Windows service is started under the SYSTEM account which is not recommended for production use due to extended permisisons permissions the account uses. To change it, use the standard Windows Services applet (Control Panel|Administrative Tools|Services) and change the user for the TeamCity Build Agent service.

Locations of the service accounts profiles:
"Local Service" - C:\Windows\ServiceProfiles\LocalService
"Network Service" - c:\Windows\ServiceProfiles\NetworkService
"System"- Has two profiles. One for 32 bit ("C:\Windows\System32\config\systemprofile") and one for 64 bit ("C:\Windows\SysWOW64\config\systemprofile").


If you start an Amazon EC2 cloud agent as a Windows service, check related notes.

The following instructions can be used to install the Windows service manually (e.g. after .zip agent installation). This procedure should also be performed to create Windows services for the second and following agents on the same machine.

To install the service:


The user account used to run the build agent service must have enough rights to start/stop the agent service, as described above.

Automatic Agent Start under Linux

To run agent automatically on the machine boot under Linux, configure daemon process with the agent.sh start command to start it and agent.sh stop command to stop it. Refer to an example procedure below

For systemd, see the example configuration file:


Description=TeamCity Build Agent


ExecStart=/home/teamcityagent/agent/bin/agent.sh start
ExecStop=-/home/teamcityagent/agent/bin/agent.sh stop

# Support agent upgrade as the main process starts a child and exits then
# Support agent upgrade as the main process gets SIGTERM during upgrade and that maps to exit code 143
SuccessExitStatus=0 143



For init.d, refer to an example procedure:

1. Navigate to the services start/stop services scripts directory:


For macOS/Mac OS X, TeamCity provides the ability to load a build agent automatically when a build user logs in. For that, TeamCity uses standard macOS way to start daemon processes - LaunchDaemon plist files.

Login Item approach (recommended)

The recommended way to start build agent on MacOS is as follows:

  • Install a build agent on a Mac via buildAgent.zip
  • Prepare the conf/buildAgent.properties file (set agent name there, at least)
  • Make sure that all files under the buildAgent directory are owned by your_build_user to ensure a proper agent upgrade process.

  • Start the build agent via bin/agent.sh start command and make sure it upgrades successfully on the first start. This may require a couple of minutes, see buildAgent/logs/teamcity-agent.log for progress.
  • Create a command file $HOME/start_build_agent.command which contains one line: 

    Code Block
    /path/to/buildAgent/bin/agent.sh start
  • Add this command file into Login Items via UI or use the following command from the Terminal app:

    Code Block
    osascript -e 'tell application "System Events" to make login item at end with properties {path:"/Users/your_build_user/start_teamcity_agent.command", hidden:false}'
  • Configure your Mac system to automatically login as a build user, as described here
  • Reboot

  • On the system startup, the build user should automatically log in, and the build agent should start from the Terminal app (you can close it after that).
LaunchAgent approach

To configure an automatic build agent startup via LaunchAgent, follow these steps:

  • Install


  • Install a build agent on a Mac via buildAgent.zip
  • Prepare the conf/buildAgent.properties file (set agent name there, at least)
  • Make sure that all files under the buildAgent directory are owned by your_build_user to ensure a proper agent upgrade process.

  • Load the build agent via command:

    Code Block
    titleRun these commands under your_build_user account
    mkdir buildAgent/logs  # Directory should be created under your_build_user user 
    sh buildAgent/bin/mac.launchd.sh load

    You have to wait several minutes for the build agent to auto-upgrade from the TeamCity server. You can watch the process in the logs:

    Code Block
    tail -f buildAgent/logs/teamcity-agent.log
  • When the build agent is upgraded and successfully connects to TeamCity server, stop it:

    Code Block
    sh buildAgent/bin/mac.launchd.sh unload
Configure automatic build agent start
  • After buildAgent upgrade from the TeamCity server, copy the buildAgent/bin/jetbrains.teamcity.BuildAgent.plist file to $HOME/Library/LaunchAgents/ directory.


You can configure to start build agent on system boot, and place plist file to /Library/LaunchDaemons directory. But in this case there could be some troubles with running GUI tests, and with build agent auto-upgrade. So we do not recommend this approach.

See this external posting for some more details on LaunchDaemons.


The old jetbrains.teamcity.BuildAgent.plist files bundled with TeamCity before 9.0.4 had a bug which prevent iOS simulator from starting on OS X Yosemite (TW-38954). The fix is to remove SessionCreate property from this file.

  • Configure your Mac system to automatically login as a build user, as described here
  • Reboot

On the system startup, the build user should automatically log in, and the build agent should start.


    • Install the second build agent in a different directory

    • In conf/buildAgent.properties, you should specify an unique name for the build agent

    • Start and upgrade second agent via bin/agent.sh script
    • In bin/jetbrains.teamcity.BuildAgent.plist file, you should specify unique "Label" parameter (which is jetbrains.teamcity.BuildAgent by default)
    • When copying jetbrains.teamcity.BuildAgent.plist file to LaunchAgents, you should give it a different name
    • a different name and port

    • In the $HOME/start_build_agent.command (see details above), add a line to start the second build agent 

Stopping the Build Agent

To stop the agent manually, run the <Agent home>\agent script with a stop parameter.


If the agent runs with a console attached, you may also press Ctrl+C in the console to stop the agent (if a build is running, it will be canceled).


Configuring Java

A TeamCity build agent is a Java application and it requires JDK version 6 or later -10 to work. Oracle Java SE JDK 8 OpenJDK 8 (e.g. by AdoptOpenJDK) 1.8.0_161 or later, 32-bit is recommended. Java download page Oracle Java 8 is also supported.

A build agent contains two processes:


The (Windows) .exe TeamCity distribution comes bundled with Java 1.8.0_161.
If you run a previous version of the TeamCity agent, you will need to repeat the agent installation to update the JVM.


If a build agent uses a Java version older than the recommended Java 8 (e.g. Java 6 or 7), you will see the corresponding warning on the agent's page and a health item in the web UI.  


Support for Java prior to version 8 will be dropped in future TeamCity versions. Consider upgrading Java on the agent if you see the warning.

It is recommended to use latest Java 8, 32 bit version. OpenJDK 8 (e.g. by AdoptOpenJDK) 1.8.0_161 or later, 32-bit is recommended. Oracle Java 8 is also supported.

To update Java on agents, do one of the following:

  • Upgrade the Java automaticallySwitch to using newer Java: if the appropriate Java version of the same bitness as the current one is detected on the agent, the agent page provides an action to upgrade the switch to using that Java automatically. Upon the action invocation, the agent process is restarted (once the agent becomes idle, i.e. finishes the current build if there is one) using the new javaJava.

    Upon the action invocation,  the path to the detected Java is saved into the conf/teamcity-agent.jvm  file,  the agent process is restarted (once the agent becomes idle, i.e. finishes the current build if there is one)  and uses the new java from the file.

  • (Windows) Since the build agent .exe installation comes bundled with the required Java, you can just manually reinstall the agent using the .exe installer obtained from the TeamCity server | Agents page.
  • Install a required Java on the agent into one of the standard locations, and restart the agent - the agent should then detect it and provide an action to use a newer Java in the web UI (see above).
  • Install a required Java on the agent and configure the agent to use it.



In a rare case of updating the Java for the process that launches the TeamCity agent, use one of the options for the agent Java upgrade.
Another way for Build Agent started as a Windows service, is to stop the service, change the wrapper.java.command variable in buildAgent\launcher\conf\wrapper.conf to point to the new java.exe binary, and restart the service.


If you use Windows installer to install additional agents and want to run the agent as a service, you will need to perform manual steps as installing second agent as a service on the same machine is not supported by the installer: the existing service is overwritten (see also a feature request).
In order to install the second agent, it is recommended to install the second agent manually (using .zip agent distribution). You can use Windows agent installer and do not opt for service installation, but you will lose uninstall option for the initially installed agent this way.
After the second agent is installed, register a new service for it as mentioned in the section above.


For step-by-step instructions on installing a second Windows agent as a service, see a related external blog post.