Install and Start TeamCity Agents

A TeamCity build agent is a piece of software which listens for the commands from the TeamCity server and starts the actual build processes. A production TeamCity setup requires installing additional build agents on dedicated machines. Before that, make sure to read notes on agent-server communication, system requirements, security, conflicting software, and the licensing policy on adding new self-hosted agents.

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:

Generating Authentication Token

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.

Last modified: 24 November 2022