Visual Studio Team Services Support

Computer screen showing a question mark. Community, documentation, and status update solutions.

VSTS status

We are here to help

What do I need to do to deploy a build agent on windows?

Deploy an agent on Windows

Last Update: 10/26/2016
Team Services | TFS 15 Preview | TFS 2015 | Previous versions (XAML builds) To build and release 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:

Requirements

Windows System Pre-requisites

Prepare permissions

Make sure you have credentials that enable you to join the agent to the pool.

Confirm you have permission

Make sure you have been added as an agent pool administrator on the Agent pools control panel tab ▼

Team Services

After you've confirmed you are an administrator, get a PAT token. It's fine to limit the scope to Agent Pools (read, manage).

TFS 15 Preview

You can use either a domain user or a local Windows user on each of your TFS AT servers. Where can I learn more about agent pools? How does the agent authenticate and communicate with the TFS AT?

Proxy

If you need to run your agent behind a web proxy, see Run the agent behind a web proxy.

Download and configure the agent

  1. Go to the Agent pools control panel tab ▼
  2. Click Download agent.
  3. Click Windows.
  4. Click the Download button.
  5. Run PowerShell as Administrator.
  6. Run the commands under Create the agent.
  7. Run
    .\config.cmd
  8. Respond to the prompts.
  9. You're asked if you want to run the agent as a service.

Run interactively

After you've configured the agent, we recommend that you first try it in interactive mode to make sure it works. Also, in some cases you might need to run the agent interactively for production use. For example, if you need to run an elevated process or run UI tests. If you configured the agent to run interactively, to run it:
.\run.cmd

Run as a service

After you've verified that the agent is working, for production use, we recommend that you run the agent as a service. The main advantage is that the agent stays more reliably in a running state. For example, it starts automatically when you restart the machine and after some kinds of failures. After you configure the agent to run as a service (see above), 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.

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.

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.

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.
  1. Set the following environment variables: batch set VSTS_HTTP_PROXY_USERNAME=proxyuser set VSTS_HTTP_PROXY_PASSWORD=proxypassword
Now you're ready to configure and run the agent as explained above.

Limitations

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 use Git, you must configure a proxy for it.
  • If you are using a task that makes a REST API call, you must configure the proxy for that task.

Q&A

What version of PowerShell do I need? Where can I get a newer version?

The Windows Agent requires PowerShell version 3 or later. To check your PowerShell version:
$PSVersionTable.PSVersion
If you need a newer version of PowerShell, you can download it:

How does the agent authenticate and communicate with the TFS AT?

The agent pool administrator role is needed only when you register an agent. At that time, the agent downloads an OAUth token so that it can listen to the queue. The account that you use in this role has no bearing on future communication between the agent and the TFS AT. When a build is run, it generates an OAuth token for the scoped identity selected on the general tab of the build definition. That token is short lived and is used to access resources on the application tier.

How do I make sure I have the latest version?

  1. Go to the Agent pools control panel tab ▼
  2. Click the pool that contains the agent.
  3. Make sure the agent is enabled.
  4. Click Agents.
  5. Click Capabilities.
  6. Look for the Agent.Version capability.
    You can check this value against the latest published agent version. See Visual Studio Team Services Build and Release Agent and check the page for the highest version number listed.
  7. To update your agents, right-click the pool, and then click Update all agents.
The agent automatically updates itself when it runs a task that requires a newer version of the agent. Note: If your agent version is older than 102.1, then you must download and configure the agent to get the newest version.

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.

Where is the Visual Studio 2013 XAML build documentation?

Visual Studio 2013 XAML build documentation

🗨 Need a fast response? Chat with our support bot

Bot is currently in beta and can help answer configuration, build, and release questions. Help us improve the experience by answering the survey after your chat.

Contact us!