This page covers:
- Installing Additional Build Agents
- Starting the Build Agent
- Stopping the Build Agent
- Configuring Java
- Installing Several Build Agents on the Same Machine
Before you can start customizing projects and creating build configurations, you need to configure build agents.
Necessary OS and environment permissions
Before the installation, please review the Conflicting Software section. In case of any issues, make sure no conflicting software is used.
Please note that in order to run a TeamCity build agent, the user account used to run the Agent requires the following privileges:
- An agent should be able to open HTTP connections to the server using the server address specified in the
serverUrlproperty (usually the same URL as server web UI)
- Unless the unidirectional agent-to-server connection supported since TeamCity 9.1 is configured, the server should be able to open HTTP connections to the agent. The port is determined using the
ownPortproperty of the
buildAgent.propertiesfile as the starting port (9090 by default), and the following IP addresses are tried:
- the address specified in the
ownAddressproperty of the
buildAgent.propertiesfile (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
- the address specified in the
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
The agent process (java) should be able to:
- open outbound HTTP connections to the server address (the same address you use in the browser to view the TeamCity UI)
- unless the unidirectional agent-to-server connection supported since TeamCity 9.1 is configured, accept inbound HTTP connections from the server to the port specified as the
ownPortproperty in the
buildAgent.propertiesfile (9090 by default). 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:
<agent home>(necessary for automatic agent upgrade),
<agent work>, and
- launch processes (to run builds).
- 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 (for take process dump functionality to work)
Reboot the machine (for agent reboot functionality to work)
- user should be able to run the
shutdowncommand (for the agent machine reboot functionality and machine shutdown functionality when running in cloud)
The build process is launched by a TeamCity agent and thus shares the environment and is executed under the OS user used by the TeamCity agent. Please ensure that the TeamCity agent is configured accordingly.
See Known Issues for related Windows Service Limitations.
Server-Agent Data Transfers
The default communication between the TeamCity server and an agent is bidirectional, i.e two HTTP connections are established: the server establishes a connection to the agents and the agent establishes a connection to the server. By default, the connections are based on HTTP, which may raise your concern if you are deploying the agent and server into non-secure network environments.
Since TeamCity 9.1, it is sufficient to set up only one connection, enabling unidirectional communication from the agent to the server.
To view whether the agent-server communication is bidirectional or unidirectional for a particular agent, navigate to Agents | <Agent Name> | Agent Summary tab, the Details section, Communication Protocol.
The bidirectional TeamCity server and agent communication is based on HTTP: the server listens for incoming connection requests from the agent, while the agent listens for incoming server requests.
The HTTP connections from the server to the agents are not secured and thus are exposing potentially sensitive data 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.
It is recommended to deploy agents and the server into a secure environment and use plain HTTP for agents-to-server communications as this reduces transfer overhead.
HTTPS agent-server connection
It is possible to setup a server to be available via the HTTPS protocol, so all the data travelling through the connections established from an agent to the server (including the download of build sources, build artifacts, build progress messages and build log) can be secured. See Using HTTPS to access TeamCity server for configuration details.
However, the data that is transferred via the connections established by the server to agents (all the settings configured on the web UI including the VCS root data) is passed via an unsecured HTTP connection.
Prior to TeamCity 9.1, you could only establish appropriate network security configurations like VPN connections between agent and server machines to secure the data. Since TeamCity 9.1 you can eliminate the server-to-agent connection by switching to unidirectional agent-to-server communication. See the next section for details.
Unidirectional Agent-to-Server Communication
Since TeamCity 9.1, it is sufficient to set up only the agent-to-server connection.
When an agent is configured for unidirectional communication, the TeamCity server does not establish a connection to the agent. Instead, at startup, the agent establishes a connection to the TeamCity Server, and polls the server periodically for server commands.
The polling protocol used for the agent-to-server connection allows for increased security when the agent-to-server connection is based on HTTPS; it also increases the agents accessibility, e.g. the agents can be behind a firewall with all incoming connections blocked or the agents can be deployed to a network different from that of the server.
Changing Communication Protocol
The communication protocol used by TeamCity agents is determined by the value of the
teamcity.agent.communicationProtocols internal property. The property accepts a comma-separated ordered list of protocols and is set to
teamcity.agent.communicationProtocols=xml-rpc,polling by default, which means that the agent tries to connect using the first protocol from this list and if it fails, it will try to connect via the second protocol in the list.
- To change the communication protocol for all agents, set the TeamCity server
teamcity.agent.communicationProtocolsinternal property. The new setting will be used by all agents which will connect to the server after the change. To change the protocol for the existing connections, restart the TeamCity server.
- By default, the agent's property is not configured; when the agent first connects to the server, it receives it from the TeamCity server. To change the protocol for an individual agent after the initial agent configuration, change the value of the
teamcity.agent.communicationProtocolsproperty in the agent's properties. The agent's property overrides the server property. After the change the agent will restart automatically upon finishing a running build, if any.
Installing Additional Build Agents
- Install a build agent using any of the following options:
- After installation, configure the agent specifying its name and the address of the TeamCity server in the
- Start the agent. If the agent does not seem to run correctly, please check the agent logs.
When the newly installed agent connects to the server for the first time, it appears on the
Unauthorized agents tab visible to administrators/users with the permissions to authorize it. Agents will not run builds until they are authorized in the TeamCity web UI. The agent running on the same computer as the server is authorized by default.
The number of authorized agents is limited by the number of agents licenses on the server. See more under Licensing Policy.
Installing via MS Windows installer
- In the TeamCity Web UI, navigate to the Agents tab.
- Click the Install Build Agents link and select MS Windows Installer to download the installer.
agentInstaller.exeWindows Installer and follow the installation instructions.
Installing via ZIP File
- Make sure a JDK(JRE) 1.6+ is properly installed on the agent computer.
- On the agent computer, make sure the
JAVA_HOMEenvironment variables are set (pointing to the installed JRE or JDK directory respectively).
- In the TeamCity Web UI, navigate to the Agents tab.
- Click the Install Build Agents link and select Zip file distribution to download the archive.
- Unzip the downloaded file into the desired directory.
- Navigate to the
<installation path>\confdirectory, locate the file called
buildAgent.dist.propertiesand rename it to
- Edit the
buildAgent.propertiesfile to specify the TeamCity server URL and the name of the agent. Please refer to Build Agent Configuration section for details on agent configuration.
Under Linux, you may need to give execution permissions to the
Installing via Agent Push
TeamCity provides functionality that allows installing a build agent to a remote host. Currently supported combinations of the server host platform and targets for build agents are:
- from the Unix-based TeamCity server, build agents can be installed to Unix hosts only (via SSH).
- from the Windows-based TeamCity server, build agents can be installed to Unix (via SSH) or Windows (via psexec) hosts.
Remote Host Requirements
There are several requirements for the remote host:
- In the TeamCity Server web UI navigate to the Agents | Agent Push tab, and click Install Agent....
If you are going to use same settings for several target hosts, you can create a preset with these settings, and use it each time when installing an agent to another remote host.
- In the Install agent dialog, either select a saved preset or choose "Use custom settings", specify the target host platform and configure corresponding settings.
Since TeamCity 9.1, agent push to a Linux system via SSH supports custom ports (the default is 22) specified as the SSH port parameter. The port specified in a preset can be overridden in the host name, e.g.
hostname.domain:2222, during the actual agent installation.
- You may need to download
Sysinternals psexec.exe, in which case you will see the corresponding warning and a link to the Administration | Tools page where you can download it.
You can use Agent Push presets in Agent Cloud profile settings to automatically install a build agent to a started cloud instance.
Starting the Build Agent
TeamCity build agents can be started manually or configured to start automatically.
To start the agent manually, run the following script:
<installation path>\bin\agent.bat start
for Linux and MacOS X:
<installation path>\bin\agent.sh start
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.
Mac OS X
Automatic Agent Start under Windows
To run agent automatically on the machine boot under Windows, you can either setup 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.
That is why it is recommended to run a TeamCity agent as a Windows service only if all the build scripts support this.
Otherwise, it is advised to use alternative ways to start a TeamCity agent automatically.
One of the ways is to configure an automatic user logon on Windows start and then configure the TeamCity agent start (via
agent.bat start) on the user logon.
Build Agent as a Windows Service
In Windows, you may want to use the build agent Windows service to allow the build agent to run without any user logged on.
If you use the Windows agent installer, you have an option to install the service in the installation wizard.
The following instruction can be used to install the service manually. This procedure should also be performed to install the second and following agents on the same machine as Windows services.
To install the service:
- Make sure there is no TeamCity Build Agent Service <build number> service already installed; if installed, uninstall the agent.
- Check that the
wrapper.java.commandproperty in the
<agent home>\launcher\conf\wrapper.conffile contains a valid path to the Java executable in the JDK installation directory. You can use
wrapper.java.command=../jre/bin/javafor the agent installed with the Windows distribution. Make sure to specify the path of the java.exe file without any quotes.
- If you want to run the agent under user account and not "System", add "wrapper.ntservice.account" and "wrapper.ntservice.password" properties to the
<agent home>\launcher\conf\wrapper.conffile with appropriate credentials
- Run the
To start the service:
(or use Windows standard Services applet)
To stop the service:
(or use Windows standard Services applet)
You can also use the Windows
net.exe utility to manage the service once it is installed.
For example (assuming the default service name):
<agent home>\launcher\conf\wrapper.conf file can also be used to alter the agent JVM parameters.
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:
1. Navigate to the services start/stop services scripts directory:
2. Open the build agent service script:
3. Paste the following into the file :
4. Set the permissions to execute the file:
5. Make links to start the agent service on the machine boot and on restarts using the appropriate tool:
For Red Hat/CentOS:
Automatic Agent Start under MacOSx
For Mac OSx, TeamCity provides the ability to load a build agent automatically when a build user logs in. For that, TeamCity uses standard Mac OS way to start daemon processes - LaunchDaemon
To configure an automatic build agent startup, follow these steps:
Install and start build agent
- Install a build agent on Mac via
- Prepare the
conf/buildAgent.propertiesfile (set agent name there, at least)
Make sure that all files under the
buildAgentdirectory are owned by
your_build_userto ensure a proper agent upgrade process.
Load the build agent via commands:
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:
When the build agent is upgraded and successfully connects to TeamCity server, stop it:
Configure automatic build agent start
After buildAgent upgrade from the TeamCity server, copy the
- Configure your Mac system to automatically login as a build user, as described here
Configure a second build agent on Mac
If you want to start several build agents on the Mac, repeat the procedure of installing and starting build agent with the following changes:
Install the second build agent in a different directory
conf/buildAgent.properties, you should specify an unique name for the build agent
- Start and upgrade second agent via
bin/jetbrains.teamcity.BuildAgent.plistfile, you should specify unique "
Label" parameter (which is
- When copying
LaunchAgents, you should give it a different name
Stopping the Build Agent
To stop the agent manually, run the
<Agent home>\agent script with a
stop to request stopping after the current build finished.
stop force to request an immediate stop (if a build is running on the agent, it will be stopped abruptly (canceled))
Under Linux, you have one more option top use:
stop kill to kill the agent process.
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).
A TeamCity Agent is a Java application and it requires JDK version 1.6 or later to work. Oracle Java SE JDK 1.7, 32 bit is recommended for TeamCity 9.0, since TeamCity 9.1 - JDK 1.8, 32 bit is recommended.
The (Windows) .exe TeamCity distribution comes bundled with Java 1.7, and since TeamCity 9.1 - with Java 1.8.
If you run a previous version of the TeamCity agent, you might need to repeat the agent installation to update the JVM.
Using x32 bit JDK is recommended. JDK is required for some build runners like IntelliJ IDEA Project, Java Inspections and Duplicates. If you do not have Java builds, you can install JRE instead of JDK.
Using of x64 bit Java is possible, but you might need to double -Xmx and -XX:MaxPermSize memory values for the main agent process (see Configuring Build Agent Startup Properties and alike section for the server).
For the .zip agent installation you need to install the appropriate Java version. Make it available via PATH or available in one of the following places:
- in the directory pointed to by the
Upgrading Java on Agents
If a build agent uses a Java version older than it is required by agent (Java 1.6 currently), you will see the corresponding warning at the agent's page in the web UI. This may happen when upgrading to a newer TeamCity version, which doesn't support an old Java version anymore. To update Java on agents, do one of the following:
- If the appropriate Java version is detected on the agent, the agent page provides an action to upgrade the Java automatically. Upon the action invocation, the agent will restart using another JVM installation.
- (Windows) Since the build agent
.exeinstallation comes bundled with the required Java, you can just reinstall the agent using the
.exeinstaller obtained from the TeamCity server | Agents page.
- Install a required Java on the agent and restart the agent - it should then detect it and provide an action to use a newer Java in web UI.
- Install a required Java on the agent and configure agent to use it.
Installing Several Build Agents on the Same Machine
You can install several TeamCity agents on the same machine if the machine is capable of running several builds at the same time.
TeamCity treats all agents equally regardless of whether they are installed on the same or on different machines.
When installing several TeamCity build agents on the same machine, please consider the following:
- The builds running on such agents should not conflict by any resource (common disk directories, OS processes, OS temp directories).
- Depending on the hardware and the builds, you may experience degraded builds' performance. Ensure there are no disk, memory, or CPU bottlenecks when several builds are run at the same time.
After having one agent installed, you can install additional agents by following the regular installation procedure (see an exception for the Windows service below), but make sure that:
- The agents are installed in separate directories.
- The agents have the distinctive
tempDirdirectories in the
- Values for the
- No builds running on the agents have the absolute checkout directory specified.
Make sure there are no build configurations with the absolute checkout directory specified (alternatively, make sure such build configurations have the "clean checkout" option enabled and they cannot be run in parallel).
Usually, for a new agent installation you can just copy the directory of the existing agent to a new place with the exception of its "temp", "work", "logs" and "system" directories. Then, modify
conf/buildAgent.properties with the new
ownPort values. Please also clear (delete or remove the value) for the
authorizationToken property and make sure the
tempDir are relative/do not clash with another agent.
If you want to install additional agents as services under Windows, do not opt for service installation during the installer wizard or install manually (see also a feature request), then
<agent>\launcher\conf\wrapper.conf file so that the
wrapper.ntservice.description properties have unique values within the computer. Then run the
<agent>\bin\service.install.bat script under a user with sufficient privileges to register the new agent service. Make sure to start the agent for the first time only after it is configured as described.
See above for the service start/stop instructions.