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, conflicting software, and security.
If you install TeamCity bundled with a Tomcat servlet container, or use the TeamCity installer for Windows, both the server and one build agent are installed on the same machine. This is not a recommended setup for production purposes because of security concerns. Moreover, the build procedure can slow down the responsiveness of the web UI and overall TeamCity server functioning.
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:
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.