Deploy an agent on Windows

Last Update: 2/14/2017

Team Services | 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:

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.

Prepare permissions

Decide which user you'll use

Decide which user account you're going to use to register the agent.

Authenticate with PAT to Team Services, TFS 2017, or TFS 2015 Update 3

  1. Sign in with the user account you plan to use in either your Visual Studio Team Services account (https://{your-account}.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.

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

Authenticate as TFS user

  • TFS 2017: You can use either a domain user or a local Windows user on each of your TFS application tiers.

  • TFS 2015 (applies only to OSX and Linux): 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 you plan to use is a Team Services account owner or a TFS server administrator? If so, then skip these steps. Otherwise you might see a message like this: Sorry, we couldn't add the identity. Please try a different identity.

  1. Open a browser and navigate to the Agent pools tab for your Team Services account or TFS server:
    • Team Services: https://{your_account}.visualstudio.com/_admin/_AgentPool
    • TFS 2017: https://{your_server}/tfs/_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, a Team Services account owner, or a TFS server administrator.

Q: I'm concerned about security. How is this account used? A: Agent communication.

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 on to Team Services or TFS, and navigate to the Agent pools tab:
    • Team Services: https://{your_account}.visualstudio.com/_admin/_AgentPool
    • TFS 2017: https://{your_server}/tfs/_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.

Server URL

  • Team Services: https://{your-account}.visualstudio.com

  • TFS: http://{your-server}:8080/tfs

Authentication type

  • Team Services: Choose PAT, and then paste the PAT token you created into the command prompt window.

  • TFS:

    TIP

    In most cases it works well to just press Enter and use the default.

    • 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 TFS 2015 Update 3, TFS 2017 or newer. After you choose PAT, paste the PAT token you created into the command prompt window.

    • 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.

    • Alternate Connect to TFS using Basic authentication. To use this method you'll first need to configure HTTPS on TFS. After you select Alternate you'll be prompted for your credentials.

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.

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 "VSTS Agent (name of your agent)".

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

Replace an agent

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.

Help on other options

To learn about other options:

.\config --help

The help provides information on authentication alternatives and unattended configuration.

Q&A

How do I run the agent behind a web proxy?

In the agent root directory, create .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 as explained above.

NOTE

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.

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"
NOTE

This procedure enables the agent infrastructure to operate behind a web proxy. Your build definition 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.

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

Web site settings and security

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

Some of these features are available only on Visual Studio Team Services and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.