Build Agent Configuration

Configuration settings of the build agent are stored in the <TeamCity Agent Home>/conf/buildAgent.properties file.

General Agent Configuration

The configuration file can store properties that will be published on the server as Agent properties and can participate in the Agent Requirements expressions. All 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

Example of the file:

## The address of the TeamCity server. The same as is used to open the TeamCity web interface in the browser.
## Note that usage of https:// is recommended
serverUrl=http://localhost:8111/

## The unique name of the agent used to identify this agent on the TeamCity server
## Use blank name to let server generate it.
## By default, this name would be created from the build agent's host name
name=Default agent

## Container directory to create default checkout directories for the build configurations.
workDir=../work

## Container directory for the temporary directories.
## Please note that the directory may be cleaned between the builds.
tempDir=../temp
 
## Container directory for agent state files and caches.
## TeamCity agent assumes ownership of the directory and can delete the content inside.
systemDir=../system

 
######################################
#   Optional Agent Properties        #
######################################
## A token which is used to identify this agent on the TeamCity server for agent authorization purposes.
## It is automatically generated and saved back on the first agent connection to the server.
authorizationToken=1234567890abcdefghijklml

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 legacy 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.

ownPort=9090

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:

ownAddress=<own IP address or server-accessible domain name>

Set up Agent behind Proxy

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:

## The domain name or the IP address of the proxy host and the port
teamcity.http.proxyHost=123.45.678.9
teamcity.http.proxyPort=8080
 
## If the proxy requires authentication, specify the login and password
teamcity.http.proxyLogin=login
teamcity.http.proxyPassword=password

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

Last modified: 27 April 2021