Install TeamCity Agent

Before installing a TeamCity build agent, make sure to read the system requirements.

Choose a convenient installation option:

using an installer on Windows
installing manually from a ZIP file on any platform
preparing a Docker container based on the official TeamCity Agent image

Install from Windows Executable File

Open the Agents page in TeamCity.
Click Install Build Agents and select Windows Installer to download the installer.
On the agent machine, run agentInstaller.exe and follow the installation instructions.

Ensure that the user account used for running the agent service has proper permissions.

Install from ZIP File

Make sure that the JRE_HOME or JAVA_HOME environment variables are set on the agent machine and respectively point to the installed JRE or JDK directories.
Open the Agents page in TeamCity.
Click Install Build Agents and select one of the two options to download the archive:
- Minimal ZIP file distribution: a regular build agent with no plugins.
- Full ZIP file distribution*: a full build agent prepacked with all plugins currently enabled on the server.
Extract the downloaded file into an arbitrary directory.
Open the <installation path>\conf directory and rename the buildAgent.dist.properties file to buildAgent.properties.
Edit the buildAgent.properties file to specify the TeamCity server URL (HTTPS is recommended, see these notes), the name of the agent, and the authentication token. Refer to this article for details on the agent configuration.

On Linux, you may need to give execution permissions to the bin/agent.sh shell script.

On Windows, you may want to install the build agent Windows service instead of using the manual agent startup.

Install via Agent Push

TeamCity provides the Agent Push functionality that allows installing a build agent to a remote host. Supported combinations of the server host platform and targets for build agents:

From a Unix-based TeamCity server, build agents can be installed to Unix hosts only (via SSH).
From a 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:

Platform	Prerequisites
Linux	Installed JDK (JRE) 8-11. The JVM should be reachable via the `JAVA_HOME` (`JRE_HOME`) global environment variable or be in the global path (instead of being specified in, for example, user's `.bashrc` file). The `unzip` utility. Either `wget` or `curl`.
Windows	Installed JDK/JRE 8-11. `Sysinternals psexec.exe` has to be installed on the TeamCity server and accessible in paths. You can install it in Administration \| Tools. Note that PsExec applies additional requirements to a remote Windows host. Make sure the following preconditions are satisfied: Administrative share on a remote host is enabled and accessible. Remote services work (MMC snap-in can connect to the machine). Remote registry works (`regedit` can connect to the machine via `services.msc`). Server and workstation services are running (check via `services.msc`). Classic network authentication is enabled. You can test the connection by the following commands: net use \\target\Admin$ /user:Administrator dir \\target\Admin$

Platform

Prerequisites

Linux

Installed JDK (JRE) 8-11. The JVM should be reachable via the JAVA_HOME (JRE_HOME) global environment variable or be in the global path (instead of being specified in, for example, user's .bashrc file).
The unzip utility.
Either wget or curl.

Windows

Installed JDK/JRE 8-11.
Sysinternals psexec.exe has to be installed on the TeamCity server and accessible in paths. You can install it in Administration | Tools. Note that PsExec applies additional requirements to a remote Windows host. Make sure the following preconditions are satisfied:
- Administrative share on a remote host is enabled and accessible.
- Remote services work (MMC snap-in can connect to the machine).
- Remote registry works (regedit can connect to the machine via services.msc).
- Server and workstation services are running (check via services.msc).
- Classic network authentication is enabled.

You can test the connection by the following commands:

  net use \\target\Admin$ /user:Administrator 
  dir \\target\Admin$ 

Installation

Note that to access the Agent Push page, a user needs to have the Administer build agent machines permission.

In the TeamCity UI, open Agents | Agent Push and click Install Agent.
If you want to use the 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. 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 (for example, 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 Administration | Tools where you can download it.

Last modified: 17 August 2022