Instead of having one common set of agents, you can break them into separate groups called agent pools. A pool is a named set of agents to which you can assign projects.

The number of agents authorized by the TeamCity server is limited by the number of agent licenses. By default, all newly authorized agents are included into the Default pool

With the help of agent pools you can bind specific agents to specific projects. Project builds can be run only on build agents from the pools assigned to the project. Agent pools can also help to calculate the required agents capacity. 

You can find all agent pools configured in TeamCity at the Agents | Pools tab.

Required Permissions

To be able to add\remove pools and set maximum number of agents in the pool, you need to have the "Manage agent pools" permission granted to the System administrator and Agent manager roles in the default TeamCity per-project authorization mode.

Assigning and un-assigning projects and agents to/from pools is restricted by the "Change agent pools associated with project" permission, which by default is a part of the Project administrator role. A user can perform the operations on the pool only if he/she has "Change agent pools associated with project" for all projects associated with all pools affected by the operation.

Se also related agent management permissions.

Managing Agent Pools

 The Agents | Pools tab allows managing pools in TeamCity.

To create a new agent pool, you need to specify its name. 

By default, a pool can contain an unlimited number of agents.  Since TeamCity 10.0, you can set a maximum number of agents in the pool (not applicable for the Default Pool). If the maximum number of agents is reached, TeamСity will not allow adding any new agents to this pool. This includes moving agents from other pools and automatic authorization of cloud agents. New cloud agents will not start if the target pool is full. 

To populate a pool with agents, click Assign agents... and select them from a list. Since an agent can belong to one pool only, assigning it to a pool will remove it from its previous pool. If this may cause compatibility problems, TeamCity will give you a warning. Removing an agent from a custom pool will return it to the Default pool. You can also assign cloud agents to a specific pool  when adding an image to a cloud profile.

Only the cloud agent images configured in the the <Root> project can be moved using Assign agents... .
To assign a pool to a cloud agent, please configure it using Agent Cloud profile, in the cloud image details.


When you have configured agent pools, you can:

See also:

Concepts: Build Agent | Agent Requirements
Administrator's Guide: Viewing Agents Workload