TFS Build 2015 (vNext) – Pools, Agents and Queues

This post is part of a series of articles on the new TFS Build vNext System.

The old build controllers and agents have been replaced by a completely new system. The old xaml system of controllers and agents is still there but it sits side by side with the newer system. Lets see what is new in the new system and talk about how to set up a Windows agent and a Linux or OSX agent.


Build agents are the things that actually execute your builds. The big news about build agents in 2015 is that they now come in two flavors, a Windows build agent for Windows machines and a cross platform agent (written in node.js) that can run on Linux and Mac OSX. That’s huge it means for the first time we can use TFS to build xcode on OSX or Java on a Linux box using Maven or Android code etc etc, thats huge.


A pool is simply a collection of agents. The main things to note about pools are

  • They are shared across all project collections – that means we can share build agents across collections, something we can’t do with xaml builds
  • A pool exists at the Team Foundation Server level. That means it’s much simpler to make your build system highly available. Have you ever tried to make a xaml build farm highly available. It isn’t a trivial task. Now with pools and queues it is much more intuitive.


Queues are the link between project collections and agents. You associate a queue with a project collection and a pool. Then you simply point your builds at a queue.

This diagram explains it all


Installing a vNext Build Agent on Windows

Its a simple task to setup a windows build agent. This video by Chris Patterson explains how and more very nicely. Try it out on your dev machine or an Azure VM. It is interesting to see Microsoft using a simple powershell script to install agents, are we seeing the beginning of the end for msi’s.

Installing a vNext Build Agent on Linux

It’s a little more involved to setup a build agent on Linux so it’s worth going over it in a bit more detail. The following is an example of setting up a cross platform build agent on Ubuntu. The same process applies to OSX or any other Linux distro and you could of course do the same thing to install a cross platform agent onto a Windows server if you so wished.

Install Node

As we discussed the cross platform is built using node so we will need node as a prerequisite. There are a million ways to install node onto your Linux machine. I personally prefer using the package manager, on Ubuntu that would be

$ curl --silent --location | sudo bash -
$ sudo apt-get install --yes nodejs

That should give the latest versions of node and npm, check that with

$ nodejs -v
$ npm -v

NB: node on Ubuntu is called nodejs due to a name clash.

Set up Permissions

We need to set up alternative credentials to allow the agent to communicate with VSO. This can be done from the user profile page


Next, go to the control panel for the account (gear in top corner) and choose to manage the security for the project collection you are working with


Add the account with alternative creds to the project collection build service accounts group


Finally on the agent pools tab, add the account to the agent pool service accounts group for the pool you want to use.


Run the installer

Download the installer using the following. The -g makes the installer globally accessible

$ sudo npm install vsoagent-installer -g

Create a folder for your agent and run the installer from within that folder

$ mkdir vsoagent01; cd vsoagent01
~/vsoagent01$ vsoagent-installer

Configure the agent

Navigate into the agent sub folder and start up the agent

~/vsoagent01$ cd agent
~/vsoagent01/agent$ nodejs vsoagent.js

You’ll be prompted to enter the username, password of the build service account, the tfs url and the name of the queue and eventually you should see your agent start.


You can Ctrl C to stop it. You can start it again using

nodejs vsoagent.js

This will run your agent in interactive mode, ideally we would run it as a service so it survives reboots but at time of writing there isn’t support for running the agent as a service on Linux, only on OSX, but it should come soon.

Wrapping Up

You might have a few packages you need to install on the build machine before you start running any builds. Remember to actually install GIT on your build machine, something I always forget to do!

Once everything is up and running I invite you to try and run a build on your Linux box, just start creating an empty build definition, set the repository settings and queue it. You should see your GIT repo being cloned to the build agent working folder, after that you can start adding tasks as you need. For a more real world example scroll down to end of this article.



4 thoughts on “TFS Build 2015 (vNext) – Pools, Agents and Queues”

  1. Nice post!
    Ive followed it exactly since im also trying to set up a VSO build agent on a linux distribution. Yet when i run the agent, the first time i configure it by filling in the fields. Its able to connect to my VSO account but then it returns me with a bad request (400) error.

    Any idea whats causing this and how to fix?


    1. Hi Karl,
      I found your stackoverflow post and I can see you are using CentOS. I would try repeating your steps on another distro (Ubunutu) to try and work out if it is an issue with CentOS or not.
      Also, are you sure node is installed correctly?


  2. Only one wrong thing presents in the article. Picture shows that you can link two queues with one Pool. In fact, it is impossible. And Miscrosoft confirms this
    Q: I’m trying to create a queue that uses an existing pool, but the controls are grayed out. Why?
    A: On the Create Queue dialog box, you can’t use an existing pool if it is already referenced by another queue. Each pool can be referenced by only one queue within a given team project collection.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s