Set environment and properties for TeamCity build agent. Reconnect. Use them in projects

By neokrates, written on May 20, 2010


  • Join date: 11-30-99
  • Posts: 224
View Counter:
Rate it
  • The setup of your CI environment is?

    View Results

    Loading ... Loading ...
  • bodytext bodytext bodytext

We start with TC master, two build agents and one project. Perpose is to introduce new system variable, let us call it exclusion.criteria. If it is defined, our project should not use the agent for the builds.


✔ TeamCity 4.x

Should also work for:

✔ TeamCity 2.x, 3.x, 5.x etc


Add variable

Login to TeamCity agent host.
Then, add new variable into TeamCity agent config file:

vim $TC_AGENT_HOME/conf/




IMPORTANT Prefix might be either system. or env. Both can be used from the project.


Activate new property. Reconnect the agent

Agent can be reconnected per command line restart, something like:

$TC_AGENT_HOME/bin/ stop
Stopping TeamCity build agent...
Sending agent shutdown command to: http://localhost:10403 
Shutdown command successfully sent. Agent will exit when idle. 
$TC_AGENT_HOME/bin/ start
Starting TeamCity build agent...
Done [1798], see log at ../logs/teamcity-agent.log

💡 REMARK. Often, the /etc/init.d/ is used to demonize and configure the agent.


Connect the agent

Agent should appear in TeamCity in Agents -> Connected Agents.
If it is not the case, you might find it in Agents -> Unauthorized Agents
Authorize or activate it.


Setup one build not to build on agents with our property

  • Select the project.
  • Go to Administration -> Your Project -> You Configuration
  • Select Agent requirements
  • Under Requirements for system properties, add: system.exclusion.criteria, condition = does not exist

💡 REMARK: You actually enter exclusion.criteria, not _system.exclusion.criteria . Teamcity prefixes itself.



If done right, the agent with property should switch its location in Agents compatibility
Compatible agents -> Incompatible agents

Thats it, have fun!! :-)

Be Sociable, Share!
Does that help to solve your problem?
VN:F [1.8.5_1061]
Rating: +2 (from 2 votes)
2 votes 'YES'  0 votes 'NO'


Be Sociable, Share!


4 Responses to “Set environment and properties for TeamCity build agent. Reconnect. Use them in projects”

  1. […] Having two (or more) build agents is great, but now all that’s going to happen is every project will just get picked up by whichever agent happens to be free.  And each agent will need to have a working copy of every project, which multiplies the disk space needed and the traffic with the VCS server.  If you have large projects, these can be real concerns.  So how do you specify that a particular agent should be associated only with a certain set of projects?  Through the use of agent environment variables, as discussed here. […]

    • Having sticky agents can really help to:
      – reduce build time (in many cases no checkout, just update);
      – reduce traffic.

      I don’t agree that every agent will store working copy of every project. After the builds agents clean the build space and archive what we want them to. There is no difference where we built the project, just Build Log and artifacts will remain.

      We have tried to create ‘sticky’ build agents, which handle particular class of projects. By doing that we have learned that agents tend to become ‘specialized’, which results in problems:
      – agents tend to become specialized mainly because people have particular problem with there build and solve it for that agent. Other agents will not be changed. With the time it is both maintainability and update problem.
      – one particular result of specialized agents that if we have new project it might require the creation of new agent, because we don’t know the current state of any sticky agent.
      – agent state and config cannot be reproduced. If it has problem, many projects just won’t build.

      The solution for that ‘specialization’ problem was to set the requirement that absolutely no specialized fixes are allowed. Only one builder class, and then allow agent< ->project setup. After that stickiness worked just fine.

  2. dragon788 says:

    In newer versions of TeamCity you no longer have to restart the agent, it will pick up the additions to the properties files automatically (at least TC 8.x and higher I think).

    • admin says:

      Hey Dragon788,

      thank you for an update. Indeed, the article describes specific version of TeamCity and was not updated for the newest.


Leave a Reply