TeamCity Agent Plan

TeamCity Agent is a lightweight, powerful tool used to execute jobs in TeamCity CI/CD pipelines. It handles tasks defined in TeamCity build configurations, such as building, testing, and deploying code. The agent fetches code from the TeamCity server, runs it in a predefined environment, and returns the results to TeamCity. For further details, refer to the official TeamCity Agent documentation.

Document Overview

This document provides instructions for adding a self-hosted agent to a TeamCity project. Self-hosted agents offer flexibility and control by running CI/CD pipelines on machines you manage, giving you full control over the build environment and resources.

Adding a Self-Hosted Agent to a Repository

  • This step is only for TeamCity Cloud projects where users want to use an authentication token to authorize their agents. This is an optional field. The token is automatically generated and assigned to the build agent when it first connects to and is authorized by the TeamCity server. Once authorized, the token is saved locally on the build agent machine.

  1. Navigate to your TeamCity project and open the Agents page.

  1. Under the Overview tab, select the Install Agent drop-down menu and select Use authentication token…

  1. Select Generate and copy and save the token. Be sure to save the token somewhere secure, as you will not be able to retrieve it again.

Setting Up your Agent on MacinCloud

  1. Log in to the MacinCloud Portal.

  2. From the dashboard, navigate to Agents > Teamcity Agent.

  1. Once selecting your agent you will see a page similar to this.

  1. Select the agent under your subscriptions.

  1. Click Actions > Edit Agent and complete the necessary fields:

    • Agent Name: Match this with the runner description from GitLab.

    • Instance Type:

      • Choose TeamCity Cloud if using the cloud-hosted version of TeamCity.

      • Choose TeamCity Professional/Enterprise if managing your own self-hosted TeamCity server.

    • Server URL:

      • For TeamCity Cloud, use the URL provided by TeamCity Cloud (e.g., https://{domain-name}.teamcity.com/).

      • For TeamCity Professional/Enterprise, enter the appropriate URL for your self-hosted server (e.g., https://teamcity.example.com).

    • Authorization Token: Enter the token generated in TeamCity earlier. This field is optional because the token is automatically generated when the agent first connects to the server. 

  1. Once done, click Update and allow up to 2 minutes for the changes to take effect.

  1.  When your agent is successfully configured, you should see the following confirmation.

How to Authorize your Newly Created Agent

  1. Navigate to your TeamCity project and open the Agents page.

  1. On the left side bar select UNAUTHORIZED AGENTS.

  1. Next, select your newly created agent, and then click Authorize.

Verifying Your Agents Connection

  1. Navigate to your TeamCity project and open the Agents page.

  1. On the left side bar select ALL POOLS, then select Default.

  1. Scroll down to agents and select the agent you recently created.

  1. Green connected indicates that the agent is online and has successfully connected and is ready for jobs.

Troubleshooting your Agent 

If your agent has not been successfully configured, it will enter an error state. Below is a common issue and how to resolve it:


Unable to find the agent directory. Please confirm the domain name is entered correctly and restart the agent.



This error typically occur when the server URL does not exist or has been incorrectly entered, preventing your TeamCity agent from connecting to your TeamCity repository. Additionally, if the authorization token is incorrectly entered, the agent will fail to be verified and be in an error state.

Steps to Resolve Unable to Find the Agent Directory Errors:

  1. Navigate to the runner in the error state and select Actions > Edit Agent.



  1. Verify the Domain Name of your Server URL is entered correctly.



  1. If any of the information appears incorrect, please replace it with the correct information and select update.



  1. If all information appears correct, navigate to the runner in the error state and click Actions > Restart.



  • If restarting the agent does not resolve the issue, please contact support.