Setting up and Running Additional Build Agents

Before you can start customizing projects and creating build configurations, you need to configure build agents.

Installing Additional 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:

Network

An agent should be able to open HTTP connections to the server (to the same URL as server web UI)
The server should be able to open HTTP connections to the agent. The port is determined by the "ownPort" property of the buildAgent.properties file (9090 by default) and the following hosts are tried:
- the host specified in the "ownAddress" property of the buildAgent.properties file (if any)
- the source host of the request received by the server when the agent establishes a connection to the server
- the address of the network interfaces on the agent machine

If the agent is behind NAT and cannot be accessed by any of addresses of the agent machine network interfaces, please specify ownAddress in the agent config.

Common 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) and accept inbound HTTP connections from the server to the port specified as the "ownPort" property in the <TeamCity agent home>/conf/buildAgent.properties file (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 <agent temp>.
launch processes (to run builds).

Windows

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)

For granting necessary permissions for unprivileged users, see Microsoft SubInACL utility. For example, to grant Start/Stop rights, you might need to execute the subinacl.exe /service browser /grant=<login name>=PTO command.

Linux

user should be able to run the shutdown command (for the agent machine reboot functionality and machine shutdown functionality when running in Amazon EC2)

Build-related Permissions 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

During TeamCity operations, both the server establishes connections to the agents and agents establish connections to the server.

Please note that by default, these connections are not secured and thus are exposing possibly sensitive data to any third party that can 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 can 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.

It is possible to setup a server to be available via the HTTPS protocol, so all the data traveling through the connections established from an agent to the server (incl. download of build's sources, artifacts of builds, 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 (build configuration settings, i.e., all the settings configured on the web UI including VCS root data) is passed via unsecured HTTP connection. For the time being TeamCity does not provide internal means to secure this data transfers (see/vote for TW-5815). If you want to secure the data you need to establish appropriate network security configurations like VPN connections between agent and server machines.

Installing Procedure

You can install a build agent using any of the following options:

Via Java Web Start
Using MS Windows installer
By downloading a zip file and installing manually

After installation, please configure the agent specifying its name and the address of the TeamCity server in its conf/buildAgent.properties file. Then 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 under Agents, where administrators can authorize it. Please note that the tab is only visible for administrators/users with the appropriate permission.

The number of authorized agents is limited by the number of agents licenses on the server. See more under Licensing Policy.

Installing via Java Web Start

Make sure JDK 1.6+ is properly installed on the computer.
On the agent computer, set up the JAVA_HOME environment variable to point to the JDK 1.6+ installation directory.
Navigate to the Agents tab in the TeamCity web UI.
Click the "Install Build Agents" link and then click "Via Java Web Start".
Follow the instructions.
You can install the build agent Windows service during the installation process or manually.

Installing via a MS Windows installer

Navigate to the Agents tab in the TeamCity web UI.
Click the "Install Build Agents" link and then click MS Windows Installer link to download the installer.
Run the agentInstaller.exe Windows Installer and follow the installation instructions.
Please ensure the user under whom the agent service is running has appropriate permissions

Installing via ZIP File

In the TeamCity Web UI, navigate to the Agents tab.
Click the Install Build Agents link and then click download zip file.
Unzip the downloaded file into the desired directory.
Make sure that you have a JDK or JRE 1.6+ installed (You will need JDK (not JRE) for some build runners like IntelliJ IDEA, Java Inspections and Duplicates). Please ensure that the JRE_HOME or JAVA_HOME environment variables are set (pointing to the installed JRE or JDK directory respectively) for the shell in which the agent will be started.
Navigate to the <installation path>\conf directory, locate the file called buildAgent.dist.properties and rename it to buildAgent.properties.
Edit the buildAgent.properties file to specify the TeamCity server URL and the name of the agent. Please refer to Build Agent Configuration section for more details on agent configuration
Under Linux, you may need to give execution permissions to the bin/agent.sh shell script.
On Windows you may also want to install the build agent windows service instead of manual agent startup.

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.

There are several requirements for the remote host:

Platform	Prerequisites
Linux	Installed JDK(JRE) 1.6+ required. 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.) Also required the'unzip' utility and either 'wget' or 'curl'.
Windows	Installed JDK/JRE 1.6+ is required. `Sysinternals psexec.exe` on the TeamCity server is required. It has to be accessible in paths. You can install it at Administration \| Tools page. Note, that PsExec applies additional requirements to remote Windows host (for example, administrative share on remote host must be accessible). Read more about PsExec.

Installation Procedure

In the TeamCity Server web UI navigate to the Agents | Agent Push tab, and click Install Agent....
Note, that if you are going to use same settings for several target hosts, you can create a preset with these settings, and use it next time when installing an agent to another remote host.
In the Install agent dialog, if you don't yet have any presets saved, select "Use custom settings", specify the target host platform and configure corresponding settings.
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 Amazon EC2 Cloud profile settings to automatically install build agent to started cloud instance.

Starting the Build Agent

To start the agent manually, run the following script:

for Windows: <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: Windows Mac OS X Linux: configure daemon process with agent.sh start command to start it and agent.sh stop command to stop it.

Stopping the Build Agent

To stop the agent manually, run the <Agent home>\agent script with a stop parameter.

Use stop to request stopping after the current build finished. Use 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).

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.command property in the <agent home>\launcher\conf\wrapper.conf file contains a valid path to the Java executable in the JDK installation directory. You can use wrapper.java.command=../jre/bin/java for the agent installed with the Windows distribution. Make sure to specify the path of the java.exe file without any quotes.
Run the <agent home>/bin/service.install.bat file.

To start the service:

Run <agent home>/bin/service.start.bat (or use Windows standard Services applet)

To stop the service:

Run <agent home>/bin/service.stop.bat (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):

net start TCBuildAgent

The <agent home>\launcher\conf\wrapper.conf file can also be used to alter the agent JVM parameters.

The user account that is used to run the build agent service should have enough rights to start/stop the agent service.

Using LaunchDaemons Startup Files on MacOSx

For MacOSx, TeamCity provides ability to load a build agent automatically either on the system startup or on a user login. Both options involve using the LaunchDaemons plist file.

To use the LaunchDaemons plist file:

Install a build agent on Mac either via buildAgent.zip or via Java web-start
Prepare the conf/buildAgent.properties file
Fix the launcher permissions, if needed: chmod +x buildAgent/launcher/bin/*
Load the build agent to LaunchDaemon via command:
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:
tail -f buildAgent/logs/teamcity-agent.log
To start the build agent:
1. On the system boot, copy the buildAgent/bin/jetbrains.teamcity.BuildAgent.plist file to the /Library/LaunchDaemons directory. And if you don't want to run your agent as root (and you probably don't), you have to edit the /Library/LaunchDaemons/jetbrains.teamcity.BuildAgent.plist file and add section like
  <key>UserName</key> <string>your_user</string>
  Also, make sure that all files under the buildAgent directory are owned by your_user to ensure a proper agent upgrade process.
2. On a user logon (for GUI applications, e.g. if you want to run an Xcode Project with a graphic interface), copy the buildAgent/bin/jetbrains.teamcity.BuildAgent.plist file to:
- /Library/LaunchAgents/ – (For all users)
- ~/Library/LaunchAgents/ – (For a specific user)
  If an agent starts automatically on OS X Yosemite then it cannot launch iOS simulator. For additional information, please refer to the corresponding issue TW-38954 and the current workaround.
To stop the build agent, run the following command:
sh buildAgent/bin/mac.launchd.sh unload

If you need to configure a TeamCity agent environment, you can change <TeamCity Agent Home>/launcher/conf/wrapper.conf (JSW configuration). For example, to make the agent see Mono installed using MacPorts on Mac OS X agent you will need to add the following line:

set.PATH=/opt/local/bin%WRAPPER_PATH_SEPARATOR%%PATH%

Configuring Java

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 (download page). The (Windows) .exe TeamCity distribution comes with Java 1.7 bundled. 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. If you do not have Java builds, you may 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:

the <Agent home>/jre directory
in the directory pointed to by the JAVA_HOME or JRE_HOME environment variables.

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 .exe installation comes bundled with the required Java, you can just reinstall the agent using the .exe installer 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 workDir and tempDir directories in the buildAgent.properties file.
Values for the name and ownPort properties of buildAgent.properties are unique.
No builds running on the agents have the absolute checkout directory specified.

Moreover, make sure you don't have build configurations with the absolute checkout directory specified (alternatively, make sure such build configurations have "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 a new "name", "ownPort" values. Please also clear (delete or remove value) for "authorizationToken" property and make sure "workDir" and "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 modify the <agent>\launcher\conf\wrapper.conf file so that the wrapper.console.title, wrapper.ntservice.name, wrapper.ntservice.displayname and 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.

Last modified: 05 June 2023