Start TeamCity Agent
When the newly installed agent connects to the server for the first time, it appears on the Agents | Unauthorized agents page visible to administrators/users with the permissions to authorize it. Agents will not run builds until they are authorized in the TeamCity UI. The agent running on the same computer as the server is authorized by default.
The number of authorized agents is limited by the number of agent licenses on the server. See more under Licensing Policy.
TeamCity build agents can be started manually or configured to start automatically.
Run the following script:
on Windows:
<installation path>\bin\agent.bat start
on Linux and macOS:
<installation path>/bin/agent.sh start
tip
The agent uses the
serverUrl
setting frombuildAgent.properties
to connect to the TeamCity server (automatically authorizing on the first connection). If the server URL is not accessible from the agent host, you might need to configure the proxy settings.
To run an agent automatically on a Windows machine launch, you can either set up the agent to run as a Windows service or use another method. Using the Windows service approach is the easiest way, but Windows applies some constraints to the processes run this way.
A TeamCity agent works reliably under a Windows service provided all the requirements are met, but it is often not the case for the build processes configured to be run on the agent. This is why it is recommended running a TeamCity agent as a Windows service only if all your build scripts support this. Otherwise, it is advised to use alternative OS-specific methods to start a TeamCity agent automatically.
One of them is to configure an automatic user logon on Windows start and then configure the TeamCity agent start (via agent.bat start
) on the user logon (for example, via Windows Task Scheduler).
On Windows, you may want to launch a TeamCity agent as a service to allow running it without any user logged in. If you use the Windows agent installer, you have an option to install the service in the installation wizard.
warning
To run builds, the build agent must be started under a user with sufficient permissions for performing a build and managing the service. By default, a Windows service is started under the SYSTEM account which is not recommended for production use due to extended permissions this account has. To change it, use the standard Windows Services applet (Control Panel | Administrative Tools | Services) and change the user for the TeamCity Build Agent service.
tip
If you start an Amazon EC2 cloud agent as a Windows service, check the related notes.
The following instructions can be used to install a Windows service manually (for example, after .zip
agent installation). This procedure should also be performed to create Windows services for the second and following agents on the same machine.
Install the service:
Check if the service with the required name and ID (see Step 4; the service name is TeamCity Build Agent by default) is not present. If installed, remove it.
Check that the
wrapper.java.command
property in the<agent home>\launcher\conf\wrapper.conf
file contains a valid path to the Java executable in the JDK installation directory. You can usewrapper.java.command=../jre/bin/java
for the agent installed from the Windows distribution file. Make sure to specify the path of thejava.exe
file without any quotes.If you want to run the agent under a user account (recommended) and not "System", add the
wrapper.ntservice.account
andwrapper.ntservice.password
properties to the<agent home>\launcher\conf\wrapper.conf
file with appropriate credentials.(for the second and following agents on the same machine) Modify the
<agent>\launcher\conf\wrapper.conf
file so that thewrapper.console.title
,wrapper.ntservice.name
,wrapper.ntservice.displayname
, andwrapper.ntservice.description
properties have unique values within the OS.Run the
<agent home>\bin\service.install.bat
script under a user with sufficient privileges to register a new agent service. Make sure to start the agent for the first time only after it is configured as described.
Start the service:
Run
<agent home>/bin/service.start.bat
(or use the standard Windows Services applet).
Stop the service:
Run
<agent home>/bin/service.stop.bat
(or use the standard Windows Services applet).
You can also use the standard Windows net.exe
utility to manage the service once it is installed. For example (assuming the default service name):
net start TCBuildAgent
The <agent home>\launcher\conf\wrapper.conf
file can also be used to alter the agent JVM parameters.
Note that the user account used to run the build agent service must have enough rights to start/stop the agent service.
To run an agent automatically on a Linux machine launch, configure a daemon process with the agent.sh start
command to start it and the agent.sh stop
command to stop it.
For systemd
, see the example teamcityagent.service
configuration file:
[Unit]
Description=TeamCity Build Agent
After=network.target
[Service]
Type=oneshot
User=teamcityagent
Group=teamcityagent
ExecStart=/home/teamcityagent/agent/bin/agent.sh start
ExecStop=-/home/teamcityagent/agent/bin/agent.sh stop
# Support agent upgrade as the main process starts a child and exits then
RemainAfterExit=yes
# Support agent upgrade as the main process gets SIGTERM during upgrade and that maps to exit code 143
SuccessExitStatus=0 143
[Install]
WantedBy=default.target
For init.d
, refer to this example procedure:
Navigate to the services` scripts directory:
cd /etc/init.d/
Open the build agent service script:
sudo vim buildAgent
Paste the following content into the file:
#!/bin/sh ### BEGIN INIT INFO # Provides: TeamCity Build Agent # Required-Start: $remote_fs $syslog # Required-Stop: $remote_fs $syslog # Default-Start: 2 3 4 5 # Default-Stop: 0 1 6 # Short-Description: Start build agent daemon at boot time # Description: Enable service provided by daemon. ### END INIT INFO #Provide the correct user name: USER="agentuser" case "$1" in start) su - $USER -c "cd BuildAgent/bin ; ./agent.sh start" ;; stop) su - $USER -c "cd BuildAgent/bin ; ./agent.sh stop" ;; *) echo "usage start/stop" exit 1 ;; esac exit 0
Set the permissions to execute the file:
sudo chmod 755 buildAgent
Make links to start the agent service on the machine boot and on restarts using the appropriate tool:
For Debian/Ubuntu:
sudo update-rc.d buildAgent defaults
For Red Hat/CentOS:
sudo chkconfig buildAgent on
For macOS, TeamCity provides the ability to load a build agent automatically when a build user logs in.
The recommended approach is to use launchd
(LaunchAgent):
To configure an automatic build agent startup via launchd
, follow these steps:
Install a build agent on via
buildAgent.zip
.Prepare the
conf/buildAgent.properties
file (set at least the agent name).Make sure that all files under the
buildAgent
directory are owned byyour_build_user
to ensure a proper agent upgrade process.Load the build agent via the command:
mkdir buildAgent/logs # Directory should be created under your_build_user user sh buildAgent/bin/mac.launchd.sh load
Run these commands under the
your_build_user
account. Wait up to several minutes for the build agent to autoupgrade from the TeamCity server. You can watch the process in the logs:tail -f buildAgent/logs/teamcity-agent.log
When the build agent upgrades and successfully connects to the TeamCity server, stop the agent:
sh buildAgent/bin/mac.launchd.sh unload
After the build agent upgrades from the TeamCity server, copy the
buildAgent/bin/jetbrains.teamcity.BuildAgent.plist
file to the$HOME/Library/LaunchAgents/
directory (you might have to create it). If you do not want TeamCity to start under the root permissions, specify theUserName
key in the.plist
file, for example:<key>UserName</key> <string>your_build_user</string>
Configure your macOS system to automatically log in as
your_build_user
, as described here.Restart the machine. On the system startup, the build user should automatically log in, and the build agent should start.
To quickly check that the build agent is running, use the following command:launchctl list | grep BuildAgent 69722 0 jetbrains.teamcity.BuildAgent
To stop the agent manually, run the <Agent home>\agent
script with the stop
parameter.
Use stop
to request stopping after the current build finished. Use stop force
to request an immediate stop (if a build is running on the agent, it will be stopped abruptly (canceled)).
Under Linux, you can also use stop kill
to kill the agent process.
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).
If a build agent has been started as a LaunchAgent
service on macOS, it can be stopped using the launchctl
utility:
launchctl unload $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent.plist
# or
launchctl remove jetbrains.teamcity.BuildAgent
Thanks for your feedback!