Configure a Build vNext Agent

I am going to show how to configure a Build vNext Agent on VSO. Microsoft recently announced the creation of a brand new build system for TFS and VSO at the Connect event last year. This new build system will eventually replace the current one and be much more modular and friendly. Happily I am in the early adopter program and the product team just made an early alpha of the service available for that program and I have been giving it a spin.

Download Team Foundation Server 2015 today

Microsoft has released a CTP of TFS 2015 that includes the vNext build system. You can download TFS 2015 and try it out today. Remember that this is not a go-live version and you should not install it in production.

In order to configure one of the vNext Build Agents on your Visual Studio Online (VSO) account you will need to create and configure your own build server. In its current preview state it is not part of the Hosted Build scenario and you have to manage it yourself. Luckily, with your MSDN you get £95 ($150) of VM time on Azure. So spinning up your own machine is free.


The new model in the VSO vNext Build system is not based on the same collection/controller model but instead is based on a “pool” model. You can add an agent to a pool and share a pool across many collections. This removed the old need to have completely separate sets of agents for each collection. Each collection does however get its own queue, which is how it gets access to the agents that belong to a pool. Each of these entities can also be secured… so no more fafing around with controllers and collections.


If you are lucky enough to have access to the new bits (you need to be in the early adopter program for now) then you get an extra tab in the administration of your account that gives you access to the queues and pools. At the moment you get to create new pools that can only be the same name as the first queue that you add to it. You can also add additional queues to an existing pool.

You can imagine that you would be able to throttle and prioritise queues and also restrict permissions. That way you might be able to have a “release” queue that has restricted permissions on who can push builds to it as well as a priority in the Pool… your release build will get serviced first. We used to have to create all separate controllers and agents to make these sorts of guarantees.

Controllers never really gave any guarantee around permissions or even priority due to the way agent reservation worked within the build workflow.Chris Patterson, TFS Build Team

Creating a VM for the VSO vNext Build Agent

At this time there is no hosted agent option so I will be spinning up a Windows Server in Azure.


I almost never use the “Quick create” for VM’s as there are far too many backed defaults that I do not like.


I have been building everything out in Windows Technical Preview of late as I always like to use the latest of everything. While there might be additional risks in using a preview OS I get to know what all of the ins and outs of the new bits will be. Happy to take my lumps for preview bits on preview bits.


As the old agent had a minimum ram of 2GB I thought I should at least have that. I have not seen any documented restrictions for the new agent, but preview documented is always a little loose.


As usual I like to keep thins neat and I am sticking to the single cloud service (resource group) for my infrastructure needs and a build agent fits that perfectly.


No need to install any extensions at this time as we have some manual work to do. Hopefully we can have these bits completed with Chocolatey or OneGet at a later time.

Pre-requisits for VSO vNext Build Agent

The only required pre-requisite is to have Visual Studio 2013 or 2015 installed which I missed the first time through and ended up with a nasty error.


So If you get a “BrowserFlowException: SP324095: Our service was unable to complete the request” error you need to go back and install Visual Studio 2013 or Visual Studio 2015. This should not be required on the final version but this is an early alpha.


In this case I have installed 2015 as I am primeralily using it now. If your build process needs other custom components then you may want to go ahead and install them yourself. For me I only need VS 2015.

Installing the VSO vNext Build Agent

We now need to download and configure the agent on the new VM and add it to our default pool on VSO.


Installing is a bit or an over-statement at the moment. It currently involves downloading a zip and running a PowerShell that it contains. To be honest I much prefer the PowerShell option to an MSI one. MSI is dead and we should not encourage its use. PowerShell is the Windows deployment tool of choice.


 At this point we then have the agent configured as a service and it should start automatically with the server.


Once the agent is started it will show up in your web access administration tab. From here you can configure the capabilities of the server and see a bunch of system detected ones…


The new build system promises to be both versatile and much simpler than its predecessor. I for one am happy with the new capabilities of the TFS build vnext and this early Christmas present form Chris Patterson is a welcome one…


…thanks Chris!

  • Morten Ostergaard

    Looks great – thanks for sharing. Could you share some more details on the build definition part as well? I cannot wait to get away from Windows Workflow…

    I tried to find a video discussing this new build system from the Connect() event, but failed. Could you provide a link?


  • Pingback: Dew Drop – January 15, 2015 (#1934) | Morning Dew()

  • Pingback: Top 10 links of the Week #48 |01/16/2015 | The SoftFluent Blog()

  • Steve

    Thanks, Martin! As Morten said, I will be so happy to get away from Windows Workflow! I love the idea of being able to just plug in tasks to create my build work flow. The product team has done very well on this.

    • Agreed… the team really do need congratulated on this… I am looking forward to it being more widely available…

  • Pingback: Create a Build vNext build definition | naked ALM - Experts in ALM, TFS & lean-agile with Scrum()

  • Pingback: Builds en Build Scripts in VSO | Vincent()

  • David Triana

    Martin, any idea on how to make this work when the server running the agent uses a proxy to connect to the web?, the setup works, but the builds always fail complaining that they cannot reach the server. I found something about the variables, HTTP_PROXY, but doesn’t seem to work. Thanks!

    • I would try bypassing the proxy (which is not nessesary from servers anyway) and see if that helps… if not then raise the question on StackOverflow…

  • Phillip Zada

    Martin, we have a build agent running locally on one of our servers (using the windows service option – NT Service/Network Service) and after a few hours/days if shows as offline. I think its something to do with the login timing out as when i reconfigure its up and running again till the next drop out. Have you come across this or can recommend any fix?

    • You should not have this problem. Have you tried using a domain account? Are you using TFS or VSTS?

      • Phillip Zada

        1. Haven’t tried domain, but if I do doesn’t our AD need to be on Azure for it to validate?
        2. Using Visual Studio Online (VSO)

        • No you don’t need AAD: it sounds like a local issue with the agent being able to ping the server. Since you are on VSTS then it’s about getting out of your network. A local domain account might help… I love ‘network service’ but as you can’t log on as that user it’s a little difficult to debug.

          The agent goes offline when the server has not had a ping in a while, so If the pings from Agent->Server are not getting through…

          • Phillip Zada

            I’ll give a domain account a go, but i think your right about the lose of ping.
            Thanks for the quick response and info.

          • Phillip Zada

            Hey Martin, throught I’d give you an update. Still happening even with AD Account instead on NT Service checked the logs noticed this entry

            MessageQueueListener.DispatchAsync – TimeoutException received

          • If you login under that user, can you access VSTS easily?

          • Phillip Zada

            yes, but prompted for username and password as normal

          • You should never be prompted for a username and password when opening a browser on your local network when authenticated. The Agent has no way to enter those details. Soundslike a proxy issue. You need to be able to seamlessly connect when logged in for the agent to work.

  • Keith Hill

    How do you configure multiple agents on a build machine? Just run the ConfigureAgent script twice?

    • Yup, but you need a new copy of the agent in a new folder. Then run its config…

      • Keith Hill

        Oh that might explain why my two agent setup wasn’t happy. I ran the configureagent script in the same folder a second time. I was wondering why settings.json only reflected the settings for the second configured agent.

  • Angshuman Chakraborty

    I want to know, if the Telephony service needs to be disabled for vNext build. I know that Telephony service needs to be disabled incase of the XAML based build controller.