Please note that in order to run a TeamCity build agent, user account that is running the agent should have the privileges described below.
- Agent should be able to open HTTP connections to the server (to the same URL as server web UI)
- Server should be able to open HTTP connections to the agent. The port is determined by "ownPort" property of
buildAgent.propertiesfile (9090 by default) and the following hosts are tried:
- host specified in the "ownAddress" property of
buildAgent.propertiesfile (if any)
- source host of the request received by the server when agent establishes connection to the server
- address of the network interfaces on the agent machine
- host specified in the "ownAddress" property of
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 process (java) should be able to open outbound HTTP connections to the server address (the same address you use in the browser to view TeamCity UI) and accept inbound HTTP connections from the server to the port specified as "ownPort" property in "<TeamCity agent home>/conf/buildAgent.properties" file (9090 by default). Please ensure that any firewalls installed on 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 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
subinacl.exe /service browser /grant=<login name>=PTO command.
- user should be able to run
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.
You can install an additional build agent agents using any of the following installation options available:
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.
Installing via Java Web Start
- Make sure JDK 1.6+ is properly installed on the computer.
- On the agent computer, set up the
JAVA_HOMEenvironment 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.
- 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.exeWindows Installer and follow the installation instructions.
Please ensure the user under whom the agent service is running has appropriate permissions
Anchor installingBuildAgentsZip installingBuildAgentsZip
- In 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 Ipr runnerIntelliJ 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>\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 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.
Installed JDK(JRE) 1.6+ required. JVM should be reachable with JAVA_HOME(JRE_HOME) environment variables or be in paths.
- In the TeamCity Server web UI navigate to 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 target host platform and configure corresponding settings.
- You may need to download
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.
<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:
sudo /usr/libexec/StartupItemContext agent.sh start
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.
Stopping the Build Agent
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 top 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).
Automatic Agent Start under Windows
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.
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 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)
- Install build agent on Mac either via
buildAgent.zipor via Java web-start
- Fix launcher permissions, if needed:
chmod +x buildAgent/launcher/bin/*
- Load 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.
/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
- To stop build agent, run the following command:
sh buildAgent/bin/mac.launchd.sh unload
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:
- in the directory pointed to by
Upgrading Java on Agents
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:
- Since build agent
.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.
- Install required Java on the agent and restart the agent - it should then detect it and suggest to restart using updated Java installation.
- Install required Java on one of the agents and then replace <build agent home>\jre with the content of installed JDK home directory. (If you do not have Java builds, you may install JRE instead of JDK).
Installing Several Build Agents on the Same Machine
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:
- 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 exception for the Windows service below), but make sure that:
- The agents are installed in the separate directories.
- The agents have distinctive
- Values for
- No builds running on the agents have absolute checkout directory specified.
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).
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