TeamCity Cloud 2023.11 Help

Configuring Build Agent Startup Properties

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, the agent launcher starts first, and then it starts the agent itself. Remember that running an agent via script is the recommended approach but you might want to run it as a service in certain cases; refer to this page for more information.

Agent Properties

For both processes mentioned 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 in your OS:

  • TEAMCITY_AGENT_MEM_OPTS — set agent memory JVM options (for 64-bit agents, consider setting -Xmx to 512 MB)

  • 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):

wrapper.app.parameter.<N>

Build Agent is Run by Launchd (macOS)

If a TeamCity agent process is started by a launchd script, you need to modify the corresponding .plist file to set up environment variables. The following .plist file entry sets JVM XMX parameter to increase the maximum memory allocation pool for a build agent to 512 MB.

<key>EnvironmentVariables</key> <dict> <key>TEAMCITY_AGENT_MEM_OPTS</key> <string>-Xmx512m</string> </dict>

Agent Launcher Properties

Only rare cases might require changing agent launcher properties. Before modifying these, make sure your problem cannot be solved by changing the 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):

wrapper.java.additional.<N>
Last modified: 04 March 2024