Setting up and Running Additional Build Agents

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

To install a build agent, follow these general steps:

Open the Agents tab
Click the Install Build Agents link located in the top-right area of the page
In the Install Build Agents pop-up, choose one of the available installation options:
When an 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 it to the server for the first time.
Agents will not run builds until they are authorized and enabled. The agent running on the same computer as the server is authorized and enabled by default.

Please note that in order to run a TeamCity agent, the user under which account the agent runs, should have the following privileges:

Log on as a service (to run as Windows service)
Start/Stop service (to run as Windows service, necessary for agent upgrade to work)
Debug programs (for take process dump functionality to work)
have write access to following directories: <agent home>, <agent work>, and <agent temp>

Installing Build Agents via Java Web Start

Make sure JDK 1.5+ is installed on the computer.
On the agent computer, set up the JAVA_HOME environment variable to point to the JDK 1.5+ 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 buildAgentsWindowsService.

Installing Build Agents via a MS Windows installer

Run the agentInstaller.exe Windows Installer and follow the installation instructions.

Installing Build Agents via a zip file

Unzip the downloaded file into the desired directory.
Make sure that you have a JDK or JRE installed (You will need JDK (not JRE) for some build runners like Ipr runner, 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 and change the properties of the installed build agent:
- serverUrl - URL of the TeamCity server (the one used to open web TeamCity UI).
- name - name of the build agent that will be visible in the web UI. All agents connected to TeamCity server must have unique names.
- ownPort - (not required) port number that agent use to accept connections from server. Please make sure there is no firewall blocking incoming connections to the port. The port must not be used by any other application installed on the computer. If you want to install several build agents on the same computer, make sure they are assigned different ports.
- ownAddress - (not required) the IP address of the computer running build agent. Required only if automatic detection fails (e.g. if there are several network interfaces on the computer).
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 buildAgentsWindowsService instead of manual agent startup.

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
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

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 current build finished. Use 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 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).

Installing and Running a 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.

To install the service:

Make sure there is no TeamCity Build Agent Service <build number> or agentd service already installed.
Run the <agent>/bin/service.install.bat file.

To start the service:

Run <agent>/bin/service.start.bat

To stop the service:

Run <agent>/bin/service.stop.bat

The new service wrapper allows to change agent JVM parameters via standard way of Java Service Wrapper library. The configuration is located at <agent>\launcher\conf\wrapper.conf

Installing Several Build Agents on the Same Machine

Several agents can be installed on a single machine. They function as separate agents and TeamCity works with them as different agents, not utilizing the fact that they share the same machine. After installing one agent you can install additional one, providing the following conditions are met:

the agents are installed in the separate directories
they have distinctive "work" and "temp" directories
buildAgent.properties is configured to have different values for name and ownPort properties

Make sure, there are no build configurations that have absolute Build Checkout Directory specified (alternatively, make sure, such build configurations have "clean checkout" option turned ON.

Under Windows, to install the additional agents as services, modify <agent>\launcher\conf\wrapper.conf to change wrapper.console.title, wrapper.ntservice.name, wrapper.ntservice.displayname and wrapper.ntservice.description properties to have distinct name within the machine.

Last modified: 20 April 2023