This page covers:
Before you can start customizing projects and creating build configurations, you need to configure build agents.
Before the installation, please review Known Issues#Conflicting Software section.
Please note that in order to run a TeamCity build agent, user account that is running the agent should have the privileges described below.
buildAgent.propertiesfile (9090 by default) and the following hosts are tried:
buildAgent.propertiesfile (if any)
If the agent is behind NAT and cannot be accessed by any of addresses of agent machine network interfaces, please specify ownAddress in the agent config.
<agent home>(necessary for automatic agent upgrade),
<agent work>, and
For granting necessary permissions for unprivileged users, see Microsoft SubInACL utility. For example, to grant Start/Stop rights you might need to execute
subinacl.exe /service browser /grant=<login name>=PTO command.
shutdowncommand (for agent machine reboot functionality and machine shutdown functionality when running in Amazon EC2)
The build process is launched by TeamCity agent and thus shares the environment and is executed under the same OS user that TeamCity agent runs under. Please ensure that TeamCity agent is configured accordingly.
See Known Issues for related Windows Service Limitations.
Please be sure to read through this section is you plan to deploy agent and server into non-secure network environments.
During TeamCity operations, both 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 agent into executing 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 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 (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.
You can install build agents using any of the following installation options available:
After installation, please configure the agent specifying it's name and address of TeamCity server in it's
Then start the agent.
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. This will connect the agent to the server for the first time.
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.
If the agent does not seem to run correctly, please check the agent logs.
JAVA_HOMEenvironment variable to point to the JDK 1.6+ installation directory.
You can install the build agent Windows service during the installation process or manually.
agentInstaller.exeWindows Installer and follow the installation instructions.
Please ensure the user under whom the agent service is running has appropriate permissions
<installation path>\confdirectory, locate the file called
buildAgent.dist.propertiesand rename it to
buildAgent.propertiesfile 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
On Windows you may also want to install the build agent windows service instead of manual agent startup.
TeamCity provide functionality that allows to install a build agent to a remote host. Currently supported combinations of server host platform and targets for build agents are:
There are several requirements for the remote host that should be met:
Installed JDK(JRE) 1.6+ required. JVM should be reachable with JAVA_HOME(JRE_HOME) environment variables or be in paths.
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.
Sysinternals psexec.exe, in which case you will see corresponding warning and a link to Administration | Server Configuration | Tools tab 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.
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
If you're running build agent on MacOS X and you're going to run Inspection builds, you may need to use the StartupItemContext utility:
To configure agent to be started automatically, see corresponding sections:
Mac OS X
Linux: configure daemon process with
agent.sh start command to start it and
agent.sh stop command to stop it.
To stop the agent manually, run the
<Agent home>\agent script with a
stop to request stopping after current build finished.
stop force to request immediate stop (if a build is running on the agent, it will be stopped abruptly (canceled))
Under Linux, you have one more option to 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).
To run agent automatically on machine boot under Windows you can either setup agent to be run as Windows service or use another way of automatic process start.
Using Windows service approach is the easiest way, but Windows applies some constraints to the processes run in this way.
TeamCity agent can work OK under Windows service (provided all the requirements are met), but is often not the case for the build processes that you will configure to be run on the agent.
That is why it is advised to run TeamCity agent as use Windows service only if all the build scripts support this.
Otherwise, it is advices to use alternative ways to start TeamCity agent automatically.
One of the ways is to configure automatic user logon on Windows start and then configure TeamCity agent start (via
agent.bat start) on user logon.
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 Windows agent installer you have an option to install the service in the installation wizard.
To run builds, the build agent should be started under a user with enough permissions for performing a build and managing the service.By default, Windows service in started under SYSTEM ACCOUNT. To change it, use the Services applet (Control Panel|Administrative Tools|Services)
The following instruction can be used to install the service manually. This procedure should also be performed to install second and following agents on the same machine as Windows services
To install the service:
<agent home>\launcher\conf\wrapper.conffile to contain valid path to Java executable in the JDK installation directory. You can use
wrapper.java.command=../jre/bin/javafor agent installed with Windows distribution.
To start the service:
To stop the service:
You can also use Windows
net.exe utility to manage the service once it is installed.
For example (assuming the default service name):
net start TCBuildAgent
<agent home>\launcher\conf\wrapper.conf can also be used to alter agent JVM parameters.
For MacOSx, TeamCity provides ability to load a build agent automatically at the system startup using LaunchDaemons
To use LaunchDaemons
buildAgent.zipor via Java web-start
chmod +x buildAgent/launcher/bin/*
sh buildAgent/bin/mac.launchd.sh load
You have to wait several minutes for the build agent to auto-upgrade from the TeamCity server.
/Library/LaunchDaemonsdirectory for automatic startup (you may need to create this directory, if it doesn't exists). This will result in the build agent starting under root. To start agent under a different user, use
sh buildAgent/bin/mac.launchd.sh unload
If you need to configure 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:
TeamCity Agent is a Java application and it requires JDK version 1.5 or later to work (JDK 1.6 is recommended as further TeamCity versions will require 1.6 for the agent).
.exe TeamCity distribution comes with appropriate Java bundled.
For .zip agent installation you need to have Java installed (available via PATH) or available in one of the following places:
If a build agent uses a Java version older than it is required by agent version, you will see the corresponding warning at the agent's page. This may happen when upgrading to a newer TeamCity version, which doesn't support an old Java version anymore. To update Java on agents you can do one of the following:
.exeinstallation comes bundled with required Java, you can just run agent
.exe(obtained from TeamCity server | Agents page) on an agent machine and it will update the Java installation that agent uses.
TeamCity treats equally all agents no matter if they are installed on the same or on different machines. However, before installing several TeamCity build agents on the same machine, please consider the following:
After having one agent installed, you can install additional agents by following the regular installation procedure (see exception for the Windows service below), but make sure that:
Moreover, make sure you don't have build configurations with 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 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" and "ownPort" values. Please also clear (delete or remove value) for "authorizationToken" property.
If you want to install additional agents as services under Windows, do not opt for service installation during installer wizard or install manually (see also a feature request), then
<agent>\launcher\conf\wrapper.conf file so that
wrapper.ntservice.description properties have unique values within the computer. Then run
<agent>\bin\service.install.bat script under user with sufficient privileges to register the new agent service.
See above for the service start/stop instructions.
Concepts: Build Agent