System Requirements

This article contains general recommendations on choosing and configuring the environment for TeamCity Agents. If you have specific questions that are not covered here, please contact our support via any convenient feedback channel.

TeamCity Agent Requirements

This section lists requirements for the environment and OS user suitable for running a TeamCity build agent process.

Choosing Agent OS/Platform

TeamCity Agent can run on any recent version of Windows, Linux, or macOS. Requirements for the agent's operating system are listed here.

Common Requirements

The agent Java process has to:

have full permissions (read/write/delete) to the following directories recursively: <Agent Home Directory> (necessary for automatic agent upgrade and agent tools support), <Agent Work Directory>, <Agent Temp Directory>, and agent system directory (set by workDir, tempDir, and systemDir parameters in the buildAgent.properties file).
be able to launch processes (to run builds).
be able to launch nested processes with the following parent process exit (used during the agent upgrade).

Requirements for Windows-based Agents

The Windows user who runs an agent process must:

be able to start/stop service (to run as Windows service, necessary for the agent upgrade to work, see also this article).
be able to debug programs (required for taking process dump functionality).
be able to reboot the machine (required for agent reboot functionality).
be a member of the Performance Monitor Users group (to be able to monitor the performance of a build agent running as a Windows service).
be able to run as a Windows service, only if the agent runs as a service (see also this article).

Note on granting rights:

To learn how to grant users necessary rights, see this article. You can assign rights to manage services with the Microsoft SubInACL utility, a command-line tool enabling administrators to directly edit security information. The tool uses the following syntax:

SUBINACL /SERVICE \\MachineName\ServiceName /GRANT=[DomainName]UserName[=Access]

For example, to grant start/stop rights, you might need to execute the command:

subinacl.exe /service TCBuildAgent /grant=<user login name>=PTO

Requirements for Linux-based Agents

The Linux user who runs an agent process must be able to run the shutdown command (for the agent machine reboot and shutdown functionality when running in a cloud environment). If you are using systemd, it should not kill the processes on the main process exit (use RemainAfterExit=yes). See also: how to set up an automatic agent start under Linux.

Every build process is launched by a TeamCity agent. It shares the environment and is executed under the OS user used by the TeamCity agent. Ensure that the TeamCity agent is configured accordingly. See Known Issues for related Windows Service Limitations.

Estimating Hardware Requirements for Agent

The agents’ hardware requirements are determined by the builds they run. Running a TeamCity agent software introduces a requirement for additional CPU time (but it can usually be neglected compared to the build process CPU requirements) and additional memory: about 500 MB. The disk space required corresponds to the disk usage by the builds running on the agent (sources checkout, downloaded artifacts, the disk space consumed during the build; all that combined for the regularly occurring builds).

Although you can run a build agent on the same machine as the TeamCity server, the recommended approach is to use a separate machine (it can be virtual) for each build agent. If you chose to install several agents on the same machine, consider the potential CPU, disk, memory, or network bottlenecks that might occur. The Performance Monitor build feature can help analyze live data.

Last modified: 07 September 2023