Install and Start TeamCity Agents

Common Build Agent Concepts

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

• 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).

Build Agent Statuses

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.

Agent-Server Data Transfer

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.

Connecting Local Agents to TeamCity Server

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:

Cloud Agents

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.

Agent Upgrade

TeamCity agents are automatically upgraded when needed. Typically, this happens when:

• the server is upgraded

• an agent plugin is added or updated on the server

• a new tool is installed

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

Agent Priority

TeamCity employs an advanced agent selection logic, considering factors like CPU count, past building performance, agent sources (cloud or local), and more, to match your builds with the most suitable agents for the job.

You can manually lower or raise the priority of a any 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 AWS-hosted cloud 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:

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.

Debug Agents Remotely

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.