Install and Start TeamCity Agents

• An agent is a piece of software that typically checks out the source code, downloads artifacts of other builds and runs the build process. It is installed and configured separately from the TeamCity server.

• Agents can be installed on both physical and cloud-hosted virtual machines.

  note

  TeamCity agents can be installed on the same machine as TeamCity server. However, for production purposes, we recommend installing them on different machines for a number of reasons, the server performance being the most important.

• TeamCity cloud allows you to rent JetBrains-hosted Agents or configure your own (self-hosted) agents.

• An agent can run builds of any compatible build configuration. Each agent can have a unique environment: architecture, operating system, installed tools, and so on. These properties define which builds an agent can run.

• An agent can run a single build at a time. The number of agents basically limits the number of parallel builds and environments in which your build processes are run.

• To ensure the smooth agent operation, you need to periodically update core software and tools of agents installed from executable files or archives. For example, after you upgrade a TeamCity server to a newer version, all cloud agents started from an existing VM image will need some time to update (this happens automatically but delays the moment your queued builds can start). To ensure your agents are always running the latest software, run them as Docker containers instead.

• Since builds can run inside Docker or Podman containers, the agent machine's OS alone does not limit the agent-project compatibility. In other words, you can run Linux-specific tasks on Windows agents and vice versa.

• A TeamCity build agent contains two processes: agent launcher (a Java process that launches the agent process) and agent (the main process for a build agent that runs as a child process for the agent launcher).

In TeamCity, a build agent can have following statuses:

All agents connected to the server must have unique agent names.

Only users with certain roles can manage agents. See this article for more information.

For a build agent configuration, refer to this section.

A TeamCity agent connects to the TeamCity server via the URL configured as the serverUrl agent property. This is called unidirectional agent-to-server connection.

Agents use unidirectional agent-to-server connection via the polling protocol: an agent establishes an HTTP(S) connection to the TeamCity Server, and polls the server periodically for server commands.

After you install a build agent locally, it needs to be configured and connected to your TeamCity server or cloud instance. Watch this video for a quick guide:

Hosting TeamCity agents in the cloud allows you implement a highly scalable solutions with new agents spinning up on demand and winding down when there are no builds to process. See the Host Build Agents in Cloud section for more information on cloud-hosted TeamCity agents.

Both JetBrains-hosted and self-hosted agents upgrade automatically when the server is upgraded. Note that receiving new files following the server upgrade may trigger an agent restart for the changes to take effect. If your self-hosted agents run under user accounts with sufficient permissions, all restarts happen automatically and do not require your input.

If you have a mix of JetBrains-hosted and self-hosted agents, TeamCity uses the following set of rules to pick an optimal agent that is the most balanced in terms of both performance and price:

• Self-hosted agents have priority over JetBrains-hosted agents

• Per-month agents have priority over per-minute agents

• If agents on any platform can run a build, TeamCity prioritizes Linux agents first, then Windows, and lastly, macOS.

• Priorities of AWS-hosted agents depend on their instance types. Smaller agents have priority over larger ones.

• Agents with the latest OS versions have priority over agents with older versions.

• Agents installed on x86_64 machines have priority over ARM agents.

You can manually lower or raise the priority of a self-hosted agent by modifying its integer teamcity.agent.priority property. This property accepts values in the -10000 ~ 10000 range with the default value of 0. For EC2 build agents, you can set this property on the Cloud Image settings page:

For other agent types, add the following line to the <TeamCity_Agent_Home>/conf/buildAgent.properties file:

teamcity.agent.priority=54

Note that TeamCity recognizes agent properties only after the agent is fully booted and connected to the server. For that reason, priorities for non-EC2 cloud agents apply only to active/running instances. Currently, only EC2 cloud images relay agent priorities before instances start.

The recommended approach to connecting a self-hosted agent to a TeamCity Cloud instance is to generate a unique authentication token for this agent. To do this, go to Agents, open the Install Build Agents menu in the upper right corner of the screen, and click Use authentication token. There are two options:

• Generate plain-text token: you need to copy the generated token and enter it in the build agent configuration file. On Windows, you will be prompted to enter it right in the Configure Build Agent Properties installation dialog.

• Download config: enter an agent name (name attribute in the build agent config) and download the entire config file. Place it as the buildAgent.properties file in the build agent directory.

Please generate own token or configuration file per each self-hosted agent.

After an agent was installed and connected, you can invoke a terminal for this agent's machine directly from the TeamCity UI. This functionality lets you remotely view agent logs, check installed software, and debug specific agent issues.

To invoke a terminal, click Agents in the TeamCity header, choose the required agent, and click Open terminal.

You can also open this terminal from the Build Results Page. In this case, the terminal opens in the checkout directory instead of the $HOME folder.

When a terminal opens, you can click the Open in a separate tab link to get a bigger client area.

The Open terminal button is available for all types of agent machines (Linux, Windows, and macOS) and invokes terminals under the same user identity who starts TeamCity agents.

To ensure your build agent is idle while you perform maintenance, disable it but do not stop it since the terminal session requires a running build agent. Stopping a build agent freezes a previously open terminal tab, preventing users from typing new commands.

For cloud agents that are automatically terminated after idling for a certain period of time, you may want to click the "Disable for maintenance..." button to keep the agent's machine running and prevent it from shutting down while you are still investigating a build problem.

The Open terminal link is visible only to users whose role permissions include the "Invoke interactive agent terminals" permission. This permission should be granted for all projects associated with the agent pool of the corresponding agent. Users with the "Project Administrator" and "System Administrator" roles have such a permission by default. As an additional precaution, each request to open a terminal is written as a new "Agent actions | Connect to agent" activity in the audit log.