You are viewing the documentation of TeamCity 2018.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.


Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


Make sure to use a performant proxy with due (high) limits on request (upload) and response (download) size and timeouts (idle timeout should be hours to support server-side checkout)Since Teamcity 2017.1.3, setting a long idle timeout is not required, as TeamCity behind a proxy server keeps the connection to the agent alive while the patch is being created on the serverat least tens of minutes and gigabyte, according to the sizes of the codebase and artifacts).

It is recommended to use a proxy capable of working with the WebSocket protocol as that helps UI to refresh sooner.

Generally, you need to configure the TeamCity server so that it "knows" about the original URL used by the client and it can generate correct absolute URLs accessible for the client. Alternatively,  the proxy should rewrite local TeamCity server absolute URLs in responses to public URLs, but since there are many locations which can use the URLs, this is usually not feasible at full scalePreferred way to achieve that is to pass original "Host" header to TeamCity. Alternative is to set "X-Forwarded-Host" header to the original "Host" header value.

Note that whenever the value of the "Host" header is changed by the proxy (while it is recommended to preserve original Host header value), the values of the Origin and Referer headers should be mapped correspondingly if they contain the original Host header value (if they do not, they should not be set in order not to circumvent TeamCity CSRF protection).


  • use a dedicated "Connector" node in the server configuration with hard-coded public URL details and make sure that the port configured in the connector is used only by the requests to the public URL configured.
  • configure proxy to pass due request headers: "Host" or "X-Forwarded-Host" (original request host), "X-Forwarded-Proto" (original request protocol), "X-Forwarded-Port" (original request port) and configure "RemoteIpValve" for the TeamCity Tomcat configuration. 
Dedicated "Connector" Node Approach


This approach can be used when the proxy server sets  "Host", "X-Forwarded-Proto", "X-Forwarded-Port" request headers to the values of the original URL.

Since TeamCity 2017.
1 the "X-Forwarded-Host" header can be used to pass the original host name instead of preserving the value of the "Host" header. Also since TeamCity 2017.1 for the majority of functionality to work,
 it is not required to set
up RemoteIpValve
 up RemoteIpValve if only a single proxy is used (i.e. the mentioned headers store only a single value).
Also, while not critical for the most setups, this approach can be used to make sure the original client IP is passed to the TeamCity server correctly. This is important for legacy agents using bidirectional communication.

Add the following into the Tomcat main <Host> node of the conf\server.xml file (see also Tomcat doc):

Code Block