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 (
nameattribute in the build agent config) and download the entire config file. Place it as thebuildAgent.propertiesfile in the build agent directory.
Please generate own token or configuration file per each self-hosted agent.
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.