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.

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.

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.