This article was written for the beta release of ASP.NET vNext. It used to be super difficult to get a vNext application up and running, but now it is slightly easier. Furthermore, ASP.NET Core has now been properly formalised and a lot of the tools mentioned in the article below have had their named changed. Please refer to the ASP.NET Core Getting Started guides.

So ASP.NET has gone cross platform which means that you'll be able to run ASP.NET websites on OS X and Linux. Of course this is great news for all developers from across the spectrum. Below is my guide on setting up ASP.NET MVC6 on Mac OS X (I'm using Yosemite).


Mono Framework

Firstly, you will need to install the Mono framework which provides an open source implementation of many features of the .NET framework. Other guides suggest building Mono from source and installing it from the command line, but having previously installed mono using a packaged installer from their website, I found that I did not need to do this. Go to and download the latest version available as a `.pkg` file. The latest version at the time of writing is `3.12.1`. Once this installation is finished, restart your terminal environment (if already open) and run this command. I prefer to use iTerm 2, but use whatever floats your boat:

mono --version

If mono has been installed properly, it should spit out this output:

Mono JIT compiler version 3.12.0 (tarball Wed Jan 28 15:32:29 GMT 2015)
Copyright (C) 2002-2014 Novell, Inc, Xamarin Inc and Contributors.
TLS: normal
SIGSEGV: altstack
Notification: kqueue
Architecture: amd64
Disabled: none
Misc: softdebug
LLVM: supported, not enabled.
GC: sgen

Note: I was previously using mono version 2 or something like that and ASP.NET MVC6 still worked so don't panic too much if your version of mono is out of date.


The K Runtime Environment (or KRE) is the runtime hosting infrastructure that allows ASP.NET vNext apps to be run cross platform. I believe the K in KRE is just a placeholder, but others have said it stands for Kestrel? The KRE allows for multiple versions of the .NET Common Language Runtime (CLR) to be run on the same machine. K Version Manager (KVM) allows you to manage which CLR you use. To install, the steps are as below: 1. Open up iTerm 2 and paste in this command:

curl | sh && source ~/.kre/kvm/ && kvm upgrade

This will download the necessary K dependencies and install them. 2. Restart iTerm 2 and hopefully all of the KRE commands will be available to you. Test this be typing `k` and you should receive the message `Please specify the command to run`. This means that KRE has been installed successfully.

NPM / Homebrew / Yeoman

Next up you'll need to download Yeoman. Yeoman provides command line generators which allow you to create projects of many types from the command line. The ASP.NET team has made up an MVC6 generator.

In order to run Yeoman you will need to have node package manager (npm) installed alongside node. If you have none of these things on your system, IMO the best way of getting hold of them is by installing Homebrew. Homebrew is a useful little tool on OS X that acts as a package manager for many command line tools and libraries. To download Homebrew, run the below command:

ruby -e "$(curl -fsSL

Then run `brew update` to ensure that you have the latest version of homebrew. To further ensure all is peachy, run `brew doctor`. Next, install node (and npm) using homebrew:

brew install node

Let it whir away for a while and then restart iTerm 2 again. Now you will able to install Yeoman. You will also probably need to install Bower which manages your apps assets like JavaScripts and SCSS files. Use the commands below:

npm install -g yo
npm install -g bower

The `-g` option instructs `npm` to install these dependencies globally across your system, not just in the current folder, meaning Yeoman and Bower will be available to you as commands from now on (usually npm will install stuff into a folder called `node_modules` inside of your current folder). Once Yeoman is installed, you will need to install the ASP.NET Yeoman generator. Use the command below to do so:

npm install -g generator-aspnet

Now you can run `yo aspnet` which will launch the Yeoman generator to create a new vNext app:

| | .--------------------------.
|--(o)--| | Welcome to the |
`---------´ | marvellous ASP.NET 5 |
( _´U`_ ) | generator! |
/___A___ '--------------------------'
| ~ |
´ ` |° ´ Y `

? What type of application do you want to create? (Use arrow keys)
❯ Empty Application
Console Application
Web Application
Web API Application
Nancy ASP.NET Application
Class Library

Use your keyboard's up and down arrows and enter key to select the type of vNext app you want to generate. Once selected, it will ask you several questions about things you want to include like the Twitter Bootstrap SASS source and whether you want to use SCSS or just plain old CSS in your app.

A basic application

Once you've finished using the generator it will create the project files in a new folder with the name you picked for the app during the generator install process.

Finally change directory to your application by running cd [yourappname]. Now you can use the KRE to run the app. Firstly you will need to run kpm restore to download .NET libraries from the NuGet API. I think also running `kpm build` will trigger the restore process. Once this is done, run k kestrel which will start your vNext app. You should simply receive a message saying:

Adams-MacBook-Pro.local ➜ nancyapp k kestrel

Now what is the address that you should visit in your browser to see your app in action? Open up the project's folder and find the file called project.json. Inside of this file, it will say something like this:

"dependencies": {
"Kestrel": "1.0.0-beta3",
"Microsoft.AspNet.Owin": "1.0.0-beta3",
"Nancy": "1.1.0"
"commands": {
"kestrel": "Microsoft.AspNet.Hosting --server Kestrel --server.urls http://localhost:5004"
"frameworks": {
"aspnet50": {}

As you can see, you can access the app on port `5004` on `localhost`. Load this URL up in your browser and you should see the vNext app. That's it for this walkthrough.

If you have any problems then leave a comment because although I have gone to great lengths to give a detailed explanation of the steps I took here to get it setup, I actually wrote this long after I did it first time around so I'm sure if you get any errors or encounter any stumbling blocks, I probably encountered them first time around!