Install TeamCity Agent

Edit page Last modified: 22 December 2021

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

Choose a convenient installation option:

Install from Windows Executable File

  1. Open the Agents page in TeamCity.

  2. Click Install Build Agents and select Windows Installer to download the installer.

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

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

  2. Open the Agents page in TeamCity.

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

  4. Extract the downloaded file into an arbitrary directory.

  5. Open the <installation path>\conf directory and rename the buildAgent.dist.properties file to buildAgent.properties.

  6. Edit the buildAgent.properties file to specify the TeamCity server URL (HTTPS is recommended, see these notes) and the name of the agent. 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.

tip

* A minimal TeamCity agent distribution does not contain plugins: the agent downloads them on the first start. The full agent contains all enabled plugins and automatically stays relevant with the current TeamCity server state. This makes its distribution archive larger but significantly reduces the time spent on the first agent run.

The full agent is the most convenient if you use scripts for creating agent images (for example, in cloud). All instances will be synchronized with the server from the start and can instantly run a build.

Note that after starting, the full agent behaves like a regular agent. If you modify the state of plugins on the TeamCity server, all active agents will need to restart to synchronize with the server.

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.

note

SSH note

Make sure the "Password" or "Public key" authentication is enabled on the target host according to your preferred authentication method.

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$

Installation

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

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

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

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

tip

You can use Agent Push presets in Agent Cloud profile settings to automatically install a build agent to a started cloud instance.