Configure Agent Installation
A build agent can be configured by adjusting in the <TeamCity Agent Home>/conf/buildAgent.properties
file.
General Agent Configuration
This Java properties 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.
Syntax reference:
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 are processed as any other symbol.
Example agent configuration file:
Make sure the file is writable for the build agent process itself. For example, that the file is updated to store its authorization token generated on the server-side.
If you install multiple TeamCity nodes behind a reverse proxy, serverUrl
should be set to the proxy URL.
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
Build Agent Port
TeamCity agents work in a unidirectional mode: they initiate all connections to the server, not the other way around. Once connected, agents periodically poll the server for new commands, such as processing queued builds. Since no incoming connections are made by the server, configuring agent machines does not involve setting up any open ports.
In a few rare cases, agents run processes that share data with other build-related processes running on a same machine. This mostly applies to running older build steps and plugins. In these cases, agents use localhost port 9090
to share this data. You can redefine this port in the buildAgent.properties
file:
Since this port is open only on localhost, it is not available for any external incoming connections.
Alternative Fetch URL
If you have a self-updating Git repository proxy that is significantly closer than the original Git repository for certain agents, you can allow these agents to download sources from this mirror. To do so, add the teamcity.git.fetchUrlMapping.<name>=<original URL> => <proxy URL>
setting to the agent configuration file. See this section for more information: Git VCS Root | General Settings.
The Configure Command
To set up the buildAgent.properties file, you can run the <Agent_folder>/bin/agent.bat
or <Agent_folder>/bin/agent.sh
script with the configure
command. This command allows you to set up core agent properties and save them to the target configuration file. If no configuration file path is specified, the changes will be saved to the default <Agent_folder>/conf/buildAgent.properties
properties.
To view the list of available parameters, run this command with the --help
flag.
Sample command that writes the server URL and sets up the custom agent 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 the TeamCity server using the following properties in the buildAgent.properties
file:
To access HTTPS endpoints (for example, GitHub-hosted repositories), configure the teamcity.https.*
properties as well.