Managing Agents

Build agents are machines that run your builds. The teamcity agent command group lets you list and inspect agents, enable or disable them, manage authorization, execute remote commands, open interactive shell sessions, and request reboots.

Listing agents

View all registered build agents:

teamcity agent list

Filtering

# Only connected agents
teamcity agent list --connected

# Only enabled agents
teamcity agent list --enabled

# Only authorized agents
teamcity agent list --authorized

# Agents in a specific pool
teamcity agent list --pool Default

# Combine filters
teamcity agent list --connected --enabled --pool Default

Limit results and output as JSON:

teamcity agent list --limit 20
teamcity agent list --json
teamcity agent list --json=id,name,connected,enabled,pool.name

agent list flags

Flag	Description
`--connected`	Show only connected agents
`--enabled`	Show only enabled agents
`--authorized`	Show only authorized agents
`-p`, `--pool`	Filter by agent pool name
`-n`, `--limit`	Maximum number of agents to display
`--json`	Output as JSON. Use `--json=` to list available fields, `--json=f1,f2` for specific fields.

Viewing agent details

View details of a specific agent by ID or name:

teamcity agent view 1
teamcity agent view Agent-Linux-01
teamcity agent view Agent-Linux-01 --web
teamcity agent view 1 --json

Enabling and disabling agents

Disable an agent to prevent it from picking up new builds:

teamcity agent disable 1
teamcity agent disable Agent-Linux-01

Enable an agent to allow it to run builds again:

teamcity agent enable 1
teamcity agent enable Agent-Linux-01

Authorizing and deauthorizing agents

Authorize a newly connected agent to allow it to run builds:

teamcity agent authorize 1
teamcity agent authorize Agent-Linux-01

Deauthorize an agent to revoke its permission to connect:

teamcity agent deauthorize 1
teamcity agent deauthorize Agent-Linux-01

Moving agents between pools

Move an agent to a different agent pool:

teamcity agent move 1 0
teamcity agent move Agent-Linux-01 2

The first argument is the agent (by ID or name), and the second argument is the target pool ID.

Viewing compatible jobs

List the build configurations that an agent can run:

teamcity agent jobs 1
teamcity agent jobs Agent-Linux-01

Show incompatible jobs with the reasons why they cannot run on the agent:

teamcity agent jobs Agent-Linux-01 --incompatible
teamcity agent jobs 1 --json

Viewing compatible and incompatible jobs

Executing remote commands

Run a command on a build agent and return the output:

teamcity agent exec 1 "ls -la"
teamcity agent exec Agent-Linux-01 "cat /etc/os-release"

Set a timeout for long-running commands:

teamcity agent exec Agent-Linux-01 --timeout 10m -- long-running-script.sh

Interactive shell sessions

Open an interactive terminal session to a build agent:

teamcity agent term 1
teamcity agent term Agent-Linux-01

This establishes a WebSocket connection to the agent and provides a shell where you can run commands directly on the agent machine. The session ends when you type exit or press Ctrl+D.

Interactive terminal session on an agent

Rebooting agents

Request a reboot of a build agent:

teamcity agent reboot 1
teamcity agent reboot Agent-Linux-01

Wait for the current build to finish before rebooting:

teamcity agent reboot Agent-Linux-01 --after-build

Skip the confirmation prompt:

teamcity agent reboot Agent-Linux-01 --yes

22 February 2026