Setting up an on premise build agent with Visual Studio Online

In this post we’ll look at how to configure an on-premise build agent to work with your visual studio online account. If you haven’t given Visual Studio Online a try yet, I suggest you head over to, sign-in using your Microsoft account, create a free VSO account and take it for a spin! If you’re new to VSO, these channel9 videos should help get you up to speed.

Create a team project and add sample code

For our purposes here, we’ll create a new team project and add a simple Windows Forms application to it and set up the build agent to build this project. After you log into VSO, select the ‘new’ link from under ‘Recent projects and teams’ section to create a new team project. I selected Agile process template and git as the underlying version control, but these aren’t necessary for our discussion here, you can try out other combinations as well.


Navigate to the newly created team project and select ‘Open with Visual Studio’. This should launch Visual Studio and might ask you for credentials to connect to VSO. Clone the repository and add a new solution to the repo, commit the changes and push them to the server. The project should now show up in the VSO portal.



Configuring the build agent

For the demo here, I’ll be using my trusty Lenovo ThinkPad as the build agent. Log into your VSO account and select the gear icon on top right of the screen to go into your account settings. Click on ‘Control Panel’ and select ‘Agent Pools’. image

Click on ‘Download agent’ to download the VSO agent binaries and the scripts to configure the agent. Save to your favorite location on the disk and extract it (for e.g. to c:\agent). You might need to unblock the zip file before extracting it, just right click on the zip file, select properties and check the ‘unblock’ box. The zip file contains the binaries for the build agent and also a powershell script, ConfigureAgent.ps1, which will help you setup the machine as a build agent.


Open a powershell prompt and navigate to c:\agent and run ConfigureAgent.ps1. This will launch a command prompt window and ask you details about the agent, here’s what to select:

Name for this agent: leave as default or give a fancy name

URL for the Team Foundation Server: your VSO account URL (in my case this was

Configure this agent against which agent pool?: default

Work folder path: leave as default

Install the agent as Windows Service: Y


Your build agent is now setup and if you go to the account settings and refresh the agent pool, you should see the new agent listed under the default pool.


And that’s it! The build agent is now ready, we just need to create a build definition which will use this agent to build our project.

Note: The last step in the build agent setup, install as windows service, is optional. But I couldn’t get the project to build if the agent isn’t installed as a windows service. I will investigate this and update later.

Create a build definition

Go to the Build tab of your team project and click on + to create a new build definition. You can start from an empty build definition; add the ‘MSBuild’ task to the definition, browse and select the solution you want to build.


Under the ‘general’ tab, choose the default queue. Remember this is what we used while creating the build agent.


Give the build definition a name and save it. Select ‘Queue build…” after this to trigger a build. Within few seconds you should see the build being run. If you want to publish the build artifacts to a file share or any other location, you can add another task to the build definition ‘Publish build artifacts’, and set it up accordingly.


One thought on “Setting up an on premise build agent with Visual Studio Online”

  1. Thanks for this tutorial. How do you manage the credentials ?
    When I run the configuration script after choosing “Install as a service” I have to enter the user account and password.
    I use my MS credentials as I am in the Admin group but I still get ErrorConnectingToTheServer.
    Am I missing something ?

Leave a Reply

Your email address will not be published. Required fields are marked *