Unable to render embedded object: File (TeamCity48.png) not found.

TeamCity 10.x and 2017.x Documentation


You are viewing the documentation of TeamCity 10.x and 2017.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.


Server-Agent Data Transfers
Server-Agent Data Transfers

Since TeamCity 10,  by by default TeamCity uses unidirectional agent-to-server connection via the polling protocol, which means that the agent establishes a connection to the TeamCity Server and polls the server periodically for server commands. 

If for some reason the polling protocol cannot be used, TeamCity switches to the fallback bidirectional communication via xml-rpc  (the default prior to TeamCity 10) , which means that two HTTP connections are established: the server establishes a connection to the agents and the agent establishes a connection to the server, which may raise your concern if you are deploying the agent and server into non-secure network environments.

To view whether the agent-server communication is unidirectional  or bidirectional or bidirectional for a particular agent, navigate to Agents | <Agent Name> | Agent Summary tab, the Details section, Communication Protocol.


The data that is transferred via the connections established by the server to agents  is is passed via an unsecured HTTP connection and thus is potentially exposed to any third party that may listen to the traffic between the server and the agents. Moreover, since the agent and server can send "commands" to each other, an attacker that can send HTTP requests and capture responses may in theory trick the agent into executing an arbitrary command and perform other actions with a security impact.


  • be able to open outbound HTTP connections to the server address (the same address you use in the browser to view the TeamCity UI)
  • if bidirectional communicationis  is used, the agent process must be able to accept inbound HTTP connections from the server to the port (specified as the ownPort property in the buildAgent.properties file, 9090 by default, next port is used if the specified port is busy). Please ensure that any firewalls installed on the agent, server machine, or in the network and network configuration comply with these requirements.
  • 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).





  1. Installed JDK(JRE) 1.6+   (1.8 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 1.6+ (1.8 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.


  • Install a build agent on 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  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