Build Agents

Key behaviours

• Agents connect outbound to the server — no inbound firewall rules needed on the agent machine
• An agent runs one build at a time by default (can be changed with multiple agent instances)
• After a build, the agent reports all its system properties to the server (OS, JDK, tools)
• Agents auto-upgrade when the server version changes — no manual agent updates needed
• If the server restarts, agents reconnect automatically

Linux agent

# Download the agent ZIP from your TeamCity server
wget http://YOUR_TC_SERVER:8111/update/buildAgent.zip

# Extract
unzip buildAgent.zip -d /opt/buildagent-2

# Configure
cat > /opt/buildagent-2/conf/buildAgent.properties << 'EOF'
serverUrl=http://YOUR_TC_SERVER:8111
name=Agent-Linux-02
workDir=../work
tempDir=../temp
systemDir=../system
EOF

# Create service user and set permissions
useradd -m tcagent
chown -R tcagent:tcagent /opt/buildagent-2

# Start
sudo -u tcagent /opt/buildagent-2/bin/agent.sh start

Windows agent (service)

# After unzipping buildAgent.zip, install as Windows service
# Edit conf/buildAgent.properties first, then:
C:\buildagent\bin\service.install.bat

# Start the service
net start "TeamCity Build Agent 2"

Running multiple agents on one machine

# Each agent needs its own directory with unique name and ports
# Agent 1: /opt/buildagent-1   name=Agent-1  ownPort=9090
# Agent 2: /opt/buildagent-2   name=Agent-2  ownPort=9091
# Both point to the same serverUrl

# buildAgent.properties for Agent 2
serverUrl=http://TC_SERVER:8111
name=Agent-Linux-02
ownPort=9091

Every agent must be authorized by a TeamCity administrator before it can run builds. This is a security measure — it prevents arbitrary machines from claiming to be build agents.

1. After starting an agent, it appears in Agents → Unauthorized Agents.
2. Click Authorize. Optionally set an agent name and assign it to an agent pool.
3. The agent moves to Connected Agents and is ready to accept builds.

Pre-authorized agents (automation)

For automated agent provisioning (CI/CD of your CI/CD), you can pre-authorize an agent by setting a token:

# In buildAgent.properties
authorizationToken=TOKEN_FROM_SERVER

# Get tokens via REST API
GET /app/rest/agents?locator=authorized:false
# Then POST to /app/rest/agents/id:<agentId> with authorized:true

Agent pools group agents logically and then associate projects with specific pools. This ensures that e.g. production deployments only run on hardened agents, or that Java builds run on agents with JDK installed.

Creating a pool

1. Administration → Agent Pools → Create new agent pool.
2. Name the pool (e.g., "Linux JDK 11 Agents", "Windows .NET Agents").
3. Assign agents to the pool from Agents → All Agents → <Agent> → Agent Pool.
4. Assign projects to use the pool: Administration → <Project> → Edit → Assign agent pools.

Agent requirements are constraints that a build configuration places on the agent that runs it. TeamCity only assigns a build to an agent that satisfies all its requirements.

Auto-detected agent properties

Agents automatically report these properties:

Adding custom requirements

In the build configuration: Agent Requirements → Add new requirement.

# conf/buildAgent.properties — full annotated reference

# REQUIRED
serverUrl=http://192.168.1.100:8111   # TeamCity server URL

# IDENTITY
name=Agent-Linux-01                   # Must be unique per server
authorizationToken=                   # Set by server after first auth

# DIRECTORIES (relative to agent root, or absolute)
workDir=../work                       # Source code checkout goes here
tempDir=../temp                       # Temp files during builds
systemDir=../system                   # Agent system data (caches, etc.)

# NETWORKING
ownPort=9090                          # Agent listens on this port for server

# JAVA
# Uncomment to use specific JDK for the agent process itself
# JAVA_HOME=/usr/lib/jvm/java-11-openjdk

# CUSTOM PROPERTIES (reported to server, usable in agent requirements)
env.DOCKER_AVAILABLE=true
env.GRADLE_VERSION=7.6
system.maven.home=/usr/share/maven

How the queue works

When a build is triggered, it enters the build queue. TeamCity assigns it to the first available compatible agent. With N agents, N builds run concurrently.

Personal build queue priority

Manually-triggered builds from a specific user can be given priority over VCS-triggered builds. Set this in Administration → Server Administration → Build Queue.

Build configuration priority

In the build configuration General Settings, set a priority (1 = lowest, 10 = highest) to ensure critical builds (e.g., main branch) get agents before lower-priority builds (e.g., feature branches).

When you upgrade the TeamCity server, agents automatically receive the updated agent distribution the next time they connect. The process:

1. Server is upgraded to new version.
2. Agent connects, detects version mismatch.
3. Agent downloads updated agent files from the server.
4. Agent restarts itself.
5. Agent reconnects and resumes accepting builds.

This happens automatically — no manual intervention needed. Agents do NOT need to be upgraded separately.

Compatibility view

Go to Agents → All Agents → <Agent> → Compatible Configurations. This shows every build configuration and whether the agent is compatible. Red entries show the specific unsatisfied requirements — the fastest way to diagnose why a build isn't being assigned to an agent.