Unable to render embedded object: File (TeamCity48.png) not found.

TeamCity 2018.x Documentation

[Documentation for Previous Versions]


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.


Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


For macOS/Mac OS X, TeamCity provides the ability to load a build agent automatically when a build user logs in.

Login Item approach (recommended)

The recommended way to start build agent on MacOS is as follows:

  • Install a build agent on a Mac via buildAgent.zip
  • Prepare the conf/buildAgent.properties file (set agent name there, at least)
  • Make sure that all files under the buildAgent directory are owned by your_build_user to ensure a proper agent upgrade process.

  • Start the build agent via bin/agent.sh start command and make sure it upgrades successfully on the first start. This may require a couple of minutes, see buildAgent/logs/teamcity-agent.log for progress.
  • Create a command file $HOME/start_build_agent.command which contains one line: 

    Code Block
    /path/to/buildAgent/bin/agent.sh start
  • Add this command file into Login Items via UI or use the following command from the Terminal app:

    Code Block
    osascript -e 'tell application "System Events" to make login item at end with properties {path:"/Users/your_build_user/start_teamcity_agent.command", hidden:false}'
  • Configure your Mac system to automatically login as a build user, as described here
  • Reboot

  • On the system startup, the build user should automatically log in, and the build agent should start from the Terminal app (you can close it after that).
LaunchAgent approach

To configure an automatic build agent startup via LaunchAgent, follow these steps:


Configure a second build agent on macOS

To quickly check that a build agent is running, use the following command:

Code Block
launchctl list | grep BuildAgent 
69722	0	jetbrains.teamcity.BuildAgent

If you want to start several build agents, repeat the procedure of installing and starting build agent with the following changes:

    • Install the second build agent in a different directory

  • .
    • In conf/buildAgent.properties

  •  specify
    • , you should specify a different

  • agent
    • name

  • .
  • Do not run buildAgent/bin/mac.launchd.sh but instead 

    • Create a copy of the $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent.plist file as $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent2.plist.

    • Edit the $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent2.plist file and set the following parameters:

      • Label parameter to jetbrains.teamcity.BuildAgent2

      • WorkingDirectory parameter to the correct path to the second build agent home

    • and port

    • In the $HOME/start_build_agent.command (see details above), add a line to start the second build
  • agent.
    • agent 

Stopping the Build Agent

To stop the agent manually, run the <Agent home>\agent script with a stop parameter.


If the agent runs with a console attached, you may also press Ctrl+C in the console to stop the agent (if a build is running, it will be canceled).

Stopping the Agent Service on Mac OS

If a build agent has been started as a LaunchAgent service, it can be stopped using the launchctl utility:

Code Block
launchctl unload $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent.plist
# or 
launchctl remove jetbrains.teamcity.BuildAgent

Configuring Java

A TeamCity build agent is a Java application and it requires JDK version 6-10 to work. OpenJDK 8 (e.g. by AdoptOpenJDK) 1.8.0_161 or later, 32-bit is recommended. Oracle Java 8 is also supported.


Usually, for a new agent installation you can just copy the directory of the existing agent to a new place with the exception of its "temp", "work", "logs" and "system" directories. Then, modify conf/buildAgent.properties with the new nameownPort values. Please also clear (delete or remove the value) for the authorizationToken property and make sure the workDir and tempDir are relative/do not clash with another agent.

If you are installing a second build agent on Mac OS, see additional details here.If you use Windows installer to install additional agents and want to run the agent as a service, you will need to perform manual steps as installing second agent as a service on the same machine is not supported by the installer: the existing service is overwritten (see also a feature request).
In order to install the second agent, it is recommended to install the second agent manually (using .zip agent distribution). You can use Windows agent installer and do not opt for service installation, but you will lose uninstall option for the initially installed agent this way.
After the second agent is installed, register a new service for it as mentioned in the section above.