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 TeamCity 2018.x documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

Skip to end of metadata
Go to start of metadata

Configuration settings of the build agent are stored in the <TeamCity Agent Home>/conf/buildagent.properties file.
The file can also store properties that will be published on the server as Agent properties and can participate in the Agent Requirements expressions.
All the system and environment properties defined in the file will be passed to every build run on the agent.

The file is a Java properties file.

A quick guide is:

  • use property_name=value<newline> syntax
  • use "#" in the first position of the line for a comment
  • use "/" instead of "\" as the path separator. If you need to include "\" escape it with another "\".
  • whitespaces within a line matter

This is an example of the file:


Please make sure that the file is writable for the build agent process itself. For example, the file is updated to store its authorization token that is generated on the server-side.

If the "name" property is not specified, the server will generate a build agent name automatically. By default, this name will be created from the build agent's host name.

The file can be edited while the agent is running: the agent detects the change and (upon finishing a running build, if any) restarts automatically  loading the new settings. 

Optional Properties

If the default polling protocol is changed in favor of bidirectional communication between the server and the agent, the server must be able to open HTTP connections to the agent.

The port where the TeamCity build agent starts and where it listens for the incoming data from the server is determined via the ownPort property (9090 by default). If the firewall is configured, make sure that the incoming connections for this port are allowed on the agent computer.


If more than one build agent is hosted on the same machine, different ports must be assigned to them via the ownPort property in buildAgent.properties file of every agent.


The IP address used by TeamCity server to connect to the build agent is automatically detected by the server when the agent first connects to TeamCity, unless the ownAddress property is defined. If the machine has several network interfaces, automatic detection may fail and it is recommended to specify the ownAddress property:


Set up Agent behind Proxy

Since TeamCity 2017.1 it is possible to configure a forward proxy server for agent-to-server connections.

On the TeamCity agent side, specify the proxy to connect to TeamCity server using the following properties in the buildAgent.properties file:

Note that the proxy has to be configured not to cache any TeamCity server responses; e.g. if you use Squid, add "cache deny all" line to the squid.conf file.


See also: