Run a self-hosted agent behind a web proxy

Azure Pipelines | TFS 2018 | TFS 2017 | TFS 2015


In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions, service connections are called service endpoints, stages are called environments, and jobs are called phases.

This topic explains how to run a v2 self-hosted agent behind a web proxy.

Azure Pipelines, TFS 2018 RTM and newer

(Applies to agent version 2.122 and newer.)

When your self-hosted agent is behind a web proxy, you can:

  • Allow your agent to connect to Azure Pipelines or TFS behind a web proxy.

  • Allow your agent to get sources in the build job and download artifacts in the release job.

  • Develop custom vsts-task-lib tasks that leverage the proxy agent configuration.

To enable the agent to run behind a web proxy, pass --proxyurl, --proxyusername and --proxypassword during agent configuration.

For example:

./config.cmd --proxyurl --proxyusername "myuser" --proxypassword "mypass"

We store your proxy credential securely on each platform. On Linux, the credential is encrypted with a symmetric key based on the machine ID. On macOS, we use the Keychain. On Windows, we use the Credential Store.


Agent version 122.0, which shipped with TFS 2018 RTM, has a known issue configuring as a service on Windows. Because the Windows Credential Store is per user, you must configure the agent using the same user the service is going to run as. For example, in order to configure the agent service run as mydomain\buildadmin, you must launch config.cmd as mydomain\buildadmin. You can do that by logging into the machine with that user or using Run as a different user in the Windows shell.

How the agent handles the proxy within a build or release job

The agent will talk to Azure DevOps/TFS service through the web proxy specified in the .proxy file.

Since the code for the Get Source task in builds and Download Artifact task in releases are also baked into the agent, those tasks will follow the agent proxy configuration from the .proxy file.

The agent exposes proxy configuration via environment variables for every task execution. Task authors need to use [vsts-task-lib]( methods to retrieve proxy configuration and handle the proxy within their task.

TFS 2017.2 and older

(You also can use this method for Azure Pipelines and newer versions of TFS, but we recommend the above method in those cases.)

In the agent root directory, create a .proxy file with your proxy server url.

echo http://name-of-your-proxy-server:8888 | Out-File .proxy

If your proxy doesn't require authentication, then you're ready to configure and run the agent. See Deploy an agent on Windows.


For backwards compatibility, if the proxy is not specified as described above, the agent also checks for a proxy URL from the VSTS_HTTP_PROXY environment variable.

Proxy authentication

If your proxy requires authentication, the simplest way to handle it is to grant permissions to the user under which the agent runs. Otherwise, you can provide credentials through environment variables. When you provide credentials through environment variables, the agent keeps the credentials secret by masking them in job and diagnostic logs. To grant credentials through environment variables, set the following variables:

$env:VSTS_HTTP_PROXY_USERNAME = "proxyuser"
$env:VSTS_HTTP_PROXY_PASSWORD = "proxypassword"


This procedure enables the agent infrastructure to operate behind a web proxy. Your build pipeline and scripts must still handle proxy configuration for each task and tool you run in your build. For example, if you are using a task that makes a REST API call, you must configure the proxy for that task.

Specify proxy bypass URLs

Create a .proxybypass file in the agent's root directory that specifies regular expressions (in ECMAScript syntax) to match URLs that should bypass the proxy. For example: