Running Multiple TeamCity Agents on the Same Machine

In a common case, we recommend installing one build agent per physical or virtual machine – this makes the builds’ behavior more predictable and allows avoiding data conflicts between them. However, if you want to run multiple parallel builds on the same machine, you can set up multiple build agents on it.

To do this, install the first build agent as usual. When installing and configuring the following agents on the same machine, remember to:

  • Use a different OS user account to install each new agent. This will prevent conflicts in user resources, like artifact caches.
  • Install each agent in a different local directory.
  • Adjust the configuration file (conf/ of each agent:
    • Set unique arbitrary values for `name` and `port`.
    • Specify relative paths to the agent’s own Working Directory (`workDir`) and Temp Directory (`tempDir`). It’s important that each agent has its own independent copy of these directories.
    • Clear (delete or remove the value) the `authorizationToken` property. Agents receive these tokens upon connecting to the server.
    • If your TeamCity On-Premises server is installed behind a reverse proxy, remember to set `serverUrl` to the proxy address.

    If you are a TeamCity Cloud user, you can generate a unique agent configuration file automatically: go to Agents, open the Install Build Agents menu in the upper right corner of the screen, and click Use authentication token. Choose the Download config option and enter an agent name (the `name` attribute in the build agent config) to download the entire config file. Place it as the `` file in the build agent directory. Revise it as described above.

  • Make sure that your build steps and scripts use relative paths to files in the build checkout directory – not absolute paths on the agents’ machine. If necessary, you can enable the clean checkout option to always fetch sources directly from a VCS repository right before a build.

This Help article describes the installation process in more detail and contains important notes for Windows and macOS machines.