Deploy an agent on Windows

Azure Pipelines | TFS 2018 | TFS 2017 | TFS 2015 | Previous versions (XAML builds)

To build and deploy Windows, Azure, and other Visual Studio solutions you'll need at least one Windows agent. Windows agents can also build Java and Android apps.

Before you begin:

Learn about agents

If you already know what an agent is and how it works, feel free to jump right in to the following sections. But if you'd like some more background about what they do and how they work, see Build and release agents.

Check prerequisites

Make sure your machine is prepared with our Windows system prerequisites.

If you're building from a Subversion repo, you must install the Subversion client on the machine.

Hardware specs

The hardware specs for your agents will vary with your needs, team size, etc. It's not possible to make a general recommendation that will apply to everyone. As a point of reference, the Azure DevOps team builds its hosted agents using the hosted agents. On the other hand, the bulk of the Azure DevOps code is built by 24-core server class machines running 4 agents apiece.

Prepare permissions

Decide which user you'll use

As a one-time step, you must register the agent. Someone with permission to administer the agent queue must complete these steps. The agent will not use this person's credentials in everyday operation, but they're required to complete registration. Learn more about how agents communicate.

Authenticate with a personal access token (PAT)

  1. Sign in with the user account you plan to use in either your Azure DevOps organization (https://{your-organization}.visualstudio.com) or your Team Foundation Server web portal (https://{your-server}:8080/tfs/).

  2. From your home page, open your profile. Go to your security details.

    test

  3. Create a personal access token.

    test

  4. For the scope select Agent Pools (read, manage) and make sure all the other boxes are cleared. If it's a deployment group agent, for the scope select Deployment group (read, manage) and make sure all the other boxes are cleared.

  5. Copy the token. You'll use this token when you configure the agent.

Authenticate as a Windows user (TFS 2015 and TFS 2017)

As an alternative, on TFS 2017, you can use either a domain user or a local Windows user on each of your TFS application tiers.

On TFS 2015, for macOS and Linux only, we recommend that you create a local Windows user on each of your TFS application tiers and dedicate that user for the purpose of deploying build agents.

Confirm the user has permission

Make sure the user account that you're going to use has permission to register the agent.

Is the user an Azure DevOps organization owner or TFS server administrator? Stop here, you have permission.

Otherwise:

  1. Open a browser and navigate to the Agent pools tab for your Azure Pipelines organization or TFS server:
    • Azure Pipelines: https://dev.azure.com/{your_organization}/_admin/_AgentPool
    • TFS 2018: https://{your_server}/DefaultCollection/_admin/_AgentPool
    • TFS 2017: https://{your_server}/tfs/DefaultCollection/_admin/_AgentPool
    • TFS 2015: http://{your_server}:8080/tfs/_admin/_AgentPool

    The TFS URL doesn't work for me. How can I get the correct URL?

  2. Click the pool on the left side of the page and then click Roles.
  3. If the user account you're going to use is not shown, then get an administrator to add it. The administrator can be an agent pool administrator, an Azure DevOps organization owner, or a TFS server administrator. If it's a deployment group agent, the administrator can be an deployment group administrator, an Azure DevOps organization owner, or a TFS server administrator. You can add a user to the deployment group administrator role in the Security tab on the Deployment Groups page in Azure Pipelines.

If you see a message like this: Sorry, we couldn't add the identity. Please try a different identity., you probably followed the above steps for an organization owner or TFS server administrator. You don't need to do anything; you already have permission to administer the agent queue.

Download and configure the agent

  1. Log on to the machine using the account for which you've prepared permissions as explained above.
  2. In your web browser, sign in to Azure Pipelines or TFS, and navigate to the Agent pools tab:
    • Azure Pipelines: https://dev.azure.com/{your_organization}/_admin/_AgentPool
    • TFS 2018: https://{your_server}/DefaultCollection/_admin/_AgentPool
    • TFS 2017: https://{your_server}/tfs/DefaultCollection/_admin/_AgentPool
    • TFS 2015: http://{your_server}:8080/tfs/_admin/_AgentPool

    The TFS URL doesn't work for me. How can I get the correct URL?

  3. Click Download agent.
  4. On the Get agent dialog box, click Windows.
  5. Click the Download button.
  6. Follow the instructions on the page to download the agent.
  7. Unpack the agent into the directory of your choice. Then run config.cmd.

Note

We recommend you configure the agent from an elevated Command Prompt.

Server URL and authentication

When setup asks for your server URL, for Azure DevOps Services, answer https://dev.azure.com/{your-organization}.

When setup asks for your server URL, for TFS, answer https://{your_server}/tfs.

When setup asks for your authentication type, choose PAT. Then paste the PAT token you created into the command prompt window.

Important

Make sure your server is configured to support the authentication method you want to use.

When you configure your agent to connect to TFS, you've got the following options:

  • Alternate Connect to TFS using Basic authentication. After you select Alternate you'll be prompted for your credentials.

  • Negotiate Connect to TFS as a user other than the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. After you select Negotiate you'll be prompted for credentials.

  • Integrated (Default) Connect a Windows agent to TFS using the credentials of the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. You won't be prompted for credentials after you choose this method.

  • PAT Supported only on Azure Pipelines and TFS 2017 and newer. After you choose PAT, paste the PAT token you created into the command prompt window. Use a personal access token (PAT) if your TFS instance and the agent machine are not in a trusted domain. PAT authentication is handled by your TFS instance instead of the domain controller.

Note

When using PAT as the authentication method, the PAT token is used only for the initial configuration of the agent. Learn more at Communication with Azure Pipelines or TFS.

Choose interactive or service mode

For guidance on whether to run the agent in interactive mode or as a service, see Agents: Interactive vs. service.

Note that if you configure as a service, the username you choose to run as should be 20 characters or less.

Run the agent

If you configured the agent to run interactively, to run it:

.\run.cmd

If you configured the agent to run as a service, it starts automatically. You can view and control the agent running status from the services snap-in. Run services.msc and look for "Azure Pipelines Agent (name of your agent)".

Note

If you need to change the agent's logon account, don't do it from the Services snap-in. Instead, see the information below to re-configure the agent.

Replace an agent

To replace an agent, follow the Download and configure the agent steps again.

When you configure an agent using the same name as an agent that already exists, you're asked if you want to replace the existing agent. If you answer Y, then make sure you remove the agent (see below) that you're replacing. Otherwise, after a few minutes of conflicts, one of the agents will shut down.

Remove and re-configure an agent

To remove the agent:

.\config remove

After you've removed the agent, you can configure it again.

Unattended config

The agent can be set up from a script with no human intervention. You must pass --unattended and the answers to all questions. Consult .\config --help for details about the required responses.

Help on other options

To learn about other options:

.\config --help

The help provides information on authentication alternatives and unattended configuration.

Capabilities

Your agent's capabilities are cataloged and advertised in the pool so that only the builds and releases it can handle are assigned to it. See Build and release agent capabilities.

In many cases, after you deploy an agent, you'll need to install software or utilities. Generally you should install on your agents whatever software and tools you use on your development machine.

For example, if your build includes the npm task, then the build won't run unless there's a build agent in the pool that has npm installed.

Important

After you install new software on an agent, you must restart the agent for the new capability to show up in the pool so that the build can run.

Q & A

What version of the agent runs with TFS 2017?

TFS version Minimum agent version
2017 RTM 2.105.7
2017.3 2.112.0

I'm running a firewall and my code is in Azure Repos. What URLs does the agent need to communicate with?

If you're running an agent in a secure network behind a firewall, make sure the agent can initiate communication with the following URLs and IP addresses.

For organizations using the *.visualstudio.com domain:

https://login.microsoftonline.com
https://app.vssps.visualstudio.com 
https://{organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com
https://{organization_name}.pkgs.visualstudio.com
https://{organization_name}.vssps.visualstudio.com

For organizations using the dev.azure.com domain:

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net

To ensure your organization works with any existing firewall or IP restrictions, ensure that dev.azure.com is open and the 13.107.6.183 and 13.107.9.183 IP addresses are allowed.

How do I run the agent with self-signed certificate?

Run the agent with self-signed certificate

How do I run the agent behind a web proxy?

Run the agent behind a web proxy

How do I set different environment variables for each individual agent?

Create a .env file under agent's root directory and put environment variables you want to set into the file as following format:

MyEnv0=MyEnvValue0
MyEnv1=MyEnvValue1
MyEnv2=MyEnvValue2
MyEnv3=MyEnvValue3
MyEnv4=MyEnvValue4

How do I configure the agent to bypass a web proxy and connect to Azure Pipelines?

If you want the agent to bypass your proxy and connect to Azure Pipelines directly, then you should configure your web proxy to enable the agent to access the following URLs.

For organizations using the *.visualstudio.com domain:

https://login.microsoftonline.com
https://app.vssps.visualstudio.com 
https://{organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com
https://{organization_name}.pkgs.visualstudio.com
https://{organization_name}.vssps.visualstudio.com

For organizations using the dev.azure.com domain:

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net

To ensure your organization works with any existing firewall or IP restrictions, ensure that dev.azure.com is open and the 13.107.6.183 and 13.107.9.183 IP addresses are allowed.

Note

This procedure enables the agent to bypass a web proxy. Your build pipeline and scripts must still handle bypassing your web proxy for each task and tool you run in your build.

For example, if you are using a NuGet task, you must configure your web proxy to support bypassing the URL for the server that hosts the NuGet feed you're using.

I'm using TFS and the URLs in the sections above don't work for me. Where can I get help?

Web site settings and security

I use TFS on-premises and I don't see some of these features. Why not?

Some of these features are available only on Azure Pipelines and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.