You are viewing the documentation of TeamCity 2018.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

Skip to end of metadata
Go to start of metadata

In TeamCity a build agent contains two processes:

  • Agent Launcher — a Java process that launches the agent process
  • Agent — the main process for a Build Agent; runs as a child process for the agent launcher

Whether you run a build agent via the agent.bat|sh script or as a Windows service, at first the agent launcher starts and then it starts the agent.


You do not need to specify any of the options unless you are advised to do by the TeamCity support team or you know what you are doing.

In this section:

Agent Properties

For both processes above you can customize the final agent behavior by specifying system properties and variables for the agent to run with.

Build Agent Is Run Via Script

Before you run the <Agent Home>\bin\agent.bat|sh script, set the following environment variables:

  • TEAMCITY_AGENT_MEM_OPTS — Set agent memory options (JVM options)
  • TEAMCITY_AGENT_OPTS — additional agent JVM options

Build Agent Is Run As Service

In the <Agent Home>\launcher\conf\wrapper.conf file, add the following lines (one per option):

  • You should add additional lines before the following line in the wrapper.conf file:

  • Please ensure to re-number all the lines after the inserted ones.

Agent Launcher Properties

It's rare that you would ever need these. Most probably you would need affecting main agent process properties described above.

Build Agent Is Run Via Script

Before you run the <Agent Home>\bin\agent.bat|sh script, set the TEAMCITY_LAUNCHER_OPTS environment variable.

Build Agent Is Run As Service

In the <Agent Home>\launcher\conf\wrapper.conf file, add the following lines (one per option, the N number should increase):


Make sure you re-number all the lines after the inserted ones.

See also:

  • No labels


  1. For a Windows build agent, how and where exactly do we specify the amount of memory that Teamcity agent (Java) should use?

    Is TEAMCITY_AGENT_MEM_OPTS to be created as an environment variable (user/system)? If yes, what is the format of the value to be provided (is '-Xmx2g' a valid value that can provided for it)?

    Will that alone suffice, or should it be referenced in some teamcity agent configuration file as well? If yes, which exact file, and what is the format of this to be provided in that file?

    An example of this will surely help users. 

    1. Hi Ramaprakash Ganesan,

      If you run the agent as a service: (Tested and verified)

      Open the  <Agent Home>\launcher\conf\wrapper.conf in a text editor and navigate to the comment line:

      # Application parameters.

      This is the section where you define the parameters used in launching the agent as a service, find the line that sets the default Xmx value, mine looked like:


      Change this value to whatever is best for your agent. If you run with the default 32 bit java you can in most cases leave the value at 512m. If you need to use 64 bit Java then set it to at least double. I set mine to -Xmx1g but 2g should be fine as well, if your agent needs to allocate that kind of memory to run your tasks.

      If you run the agent via the bat files: (Tested and verified)

      Open a CMD console window as admin (On WIn10 just hit 'Win+X' then 'a')

      type this to see if the parameter we need to set is already set, so we know what its current value is:


      if it is not set or does not have the value you want, type the following (example with my value of 1g):

      setx TEAMCITY_AGENT_MEM_OPTS -Xmx1g /m

      If you need to set other parameters for memory management, like initial memory allocation (-Xms) specify that in the same system parameter, but remember "" because you now have a value with white-spaces. Example:

      setx TEAMCITY_AGENT_MEM_OPTS "-Xms512m -Xmx1g" /m

      You should not need to set anything other than Xmx though, and typically the reason for specifying more memory is that you have set the agent to run with Java 64 bit, rather than 32 bit.

      Note the '/m' means it sets this parameter on the local machine, and not current user. If the you want the parameter to be set on the current user simply omit that flag. Be aware that any parameter set in current user, with the same name as a parameter set under local machine, will always be used instead of the one set under local machine.

      1. Hi Daniel Heeris,

        Thanks for the above! very informative.

        What happens to the wrapper conf changes upon a Team City Agent upgrade, are these changes lost?


        1. You are welcome Darren Gipson. In my experience it does not get overriden when the agent upgrades, i.e. your changes are preserved, and this is also reflected in their documentation: https://confluence.jetbrains.com/display/TCD10/Upgrade#Upgrade-UpgradingtheBuildAgentWindowsServiceWrapper

          "If the service wrapper needs an update, the new version is downloaded into the <agent>/launcher.latest folder, however the changes are not applied automatically."

          That being said, I am forever paranoid with anything computers, I would recommend taking a backup of the wrapper.conf whenever you make changes to it, perhaps keep a global template somewhere if you have many agents. This also makes it easier for you to roll a new agent with similar config needs.


  2. We want to enable JMX in JAVA_OPTS so that we can monitor teamcity agent process in Zabbix, can same thing be done in TEAMCITY_AGENT_OPTS ?