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.

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

tip

It is recommended using HTTPS for agent-to-server communications (check related server configuration notes). If the agents and the server are deployed in a secure environment, agents can be configured to use plain HTTP URL for connections to the server as this reduces transfer overhead. Note that the data travelling through the connection established from an agent to the server includes build settings, repository access credentials and keys, repository sources, build artifacts, build progress messages, and build log. In case of using the HTTP protocol that data can be compromised via the " man in the middle " attack.

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:

tip

Please note that the Use authentication token... option referenced in the video is currently available only for TeamCity Cloud instances.

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.

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.

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:

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.

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.

tip

The "Open interactive terminal" link opens in the <SERVER-URL>/plugins/teamcity-agent-terminal/agentTerminal.html?agentId:<ID> URL in a separate panel or a browser tab. If your server is behind a proxy, ensure your proxy configuration allows websocket connections to this page.

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.