Build Agents Configuration and Maintenance
Viewing TeamCity Agents Details
The Agents page of the TeamCity web UI provides the comprehensive information on the TeamCity agents. The number of tabs on the page may differ depending on your agent setup.
Connected / Disconnected
The Connected and Disconnected tabs display the agents by Agent pool (default). To view the agents alphabetically, uncheck the Group by agent pool box.
For each pool TeamCity displays the status of its build agents. Clicking the arrow next to the pool displays the list of the pools agents with their statuses.
Enabling/Disabling Agents via UI
TeamCity distributes builds only among the enabled agents. Agents can be manually enabled/disabled via the web UI by clicking the status icon (1) next to the agent's name. Optionally, you can tell TeamCity to automatically disable/enable the agent after a period of time and enter your comment. TeamCity will follow the instructions and show the comment icon (2). Hovering over the icons will display the related information (3).
When you click Disable for maintenance, a cloud agent switches to maintenance mode. In this mode, the agent will not be terminated, and you can log in to the agent, view its log, and perform other operations. Also, the agent will not be available for new builds by default.
Pools
Refer to a separate page for information on configuring agent pools in TeamCity.
Parameters Report
Filter all available agents using a specified parameter.
Matrix and Statistics
Refer to a separate page for information on viewing the agents workload.
Cloud
Lists all configured agent cloud profiles.
Diff
Compare two agents and see their differences highlighted.
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.
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 closes the terminal browser tab.
For cloud agents that are automatically terminated after idling for a certain period of time, click the "Disable for maintenance..." button to keep the agent's machine running.
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.