Getting Started


To install the latest stable release with the command-line tool:

sudo npm -g install sails

On Windows (or Mac OS with Homebrew), you don't need sudo:

npm -g install sails

You may see some npm WARN deprecated messages when installing Sails. These can be safely ignored. They don’t come from Sails itself, but rather from some packages that Sails relies on--packages which themselves rely on some older modules. The Sails team is committed to keeping the framework secure and stable, and sometimes that (counter-intuitively) requires using some older versions of packages. See this thread for more info about the warnings, and this one for a discussion about updating dependencies in general.

Creating a New Sails Project

Create a new app:

sails new testProject

Now lift the server:

cd testProject
sails lift

At this point, if you visit (http://localhost:1337/) you will see the default home page.

Now, let's get Sails to do cool stuff.

New to Node.js?

That's okay! We'll get you pointed in the right direction.


"Node.js is a platform built on Chrome's JavaScript runtime for easily building fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices."

More simply put, Node.js allows us to quickly and efficiently run JavaScript code outside the browser, making it possible to use the same language on both the frontend and the backend.

What OS do I need?

Node.js will install on most major Operating systems. MacOSX, many flavors of Linux, and Windows are supported.

Now, lets take a look at what OS you have. Please choose from the following for instructions on setting up Node.js:

I have Mac OSX

I have Linux

I have Windows

Install on OSX

Using a package:

Simply download Macintosh Installer.

Using homebrew:

brew install node

Using macports:

port install nodejs

Install on Linux

Ubuntu, Mint

Example install:

sudo apt-get install python-software-properties python g++ make
curl -sL | sudo -E bash -
sudo apt-get install -y nodejs

It installs current stable Node on the current stable Ubuntu. Quantal (12.10) users may need to install the software-properties-common package for the add-apt-repository command to work: sudo apt-get install software-properties-common

There is a naming conflict with the node package (Amateur Packet Radio Node Program), and the nodejs binary has been renamed from node to nodejs. You'll need to symlink /usr/bin/node to /usr/bin/nodejs or you could uninstall the Amateur Packet Radio Node Program to avoid that conflict.


Node.js and npm are available in Fedora 18 and later. Just use your favorite graphical package manager or run this on a terminal to install both npm and node:

sudo yum install npm

RHEL/CentOS/Scientific Linux 6

Node.js and npm are available from the Fedora Extra Packages for Enterprise Linux (EPEL) testing repository. If you haven't already done so, first enable EPEL and then run the following command to install node and npm:

su -c 'yum --enablerepo=epel-testing install npm'

Arch Linux

Node.js is available in the Community Repository.

pacman -S nodejs


Node.js is available in official gentoo portage tree. You have to unmask it.

# emerge -aqv --autounmask-write nodejs
# etc-update
# emerge -aqv nodejs

Debian, LMDE

For Debian sid (unstable), Node.js is available in the official repo.

For Debian Wheezy (stable), Node.js is available in wheezy-backports. To install backports, add this to your sources.list (/etc/apt/sources.list):

deb wheezy-backports main

Then run:

apt-get update
apt-get install nodejs

For Debian Squeeze (oldstable), your best bet is to compile node by yourself (as root):

apt-get install python g++ make
mkdir ~/nodejs && cd $_
wget -N
tar xzvf node-latest.tar.gz && cd `ls -rd node-v*`
make install

openSUSE & SLE

Node.js stable repos list. Also node.js is available in openSUSE:Factory repository.

Available RPM packages for: openSUSE 11.4, 12.1, Factory and Tumbleweed; SLE 11 (with SP1 and SP2 variations).

Example install on openSUSE 12.1:

sudo zypper ar NodeJSBuildService
sudo zypper in nodejs nodejs-devel

FreeBSD and OpenBSD

Node.js is available through the ports system.


Development versions are also available using ports

cd /usr/ports/www/node-devel/ && make install clean

or packages on FreeBSD

pkg_add -r node-devel

The Node Package Manager is not installed along with Node.js by default on FreeBSD and will be needed for development and installing dependencies.


Also note that FreeBSD 10 using clang will conflict with the occasional build scrpt (which assumes gcc) using node-gyp, and can be resolved by setting an envvar.


Install on Windows

Using a package:

Simply download Windows Installer.

Using chocolatey to install Node:

cinst nodejs

or for full install with NPM:

cinst nodejs.install

On to Sails.js!

Once Node.js is installed on your system, you can go ahead and install Sails.

Further help!

We know that sometimes things don't go as planned. If you still have any issue with this, please feel free to visit Node.js's IRC Channel or our own IRC Channel.

What is Sails?

Sails is, of course, a web framework. But take a step back. What does that mean? Sometimes, when we refer to the "web", we mean the "front-end web." We think of concepts like web standards, or HTML 5, or CSS 3; and frameworks like Backbone, or Angular, or jQuery. Sails is not "that kind" of a web framework. Sails works great with Angular and Backbone, but you would never use Sails instead of those libraries.

On the other hand, sometimes when we talk about "web frameworks", we mean the "back-end web." This evokes concepts like REST, or HTTP, or WebSockets; and technologies like Java, or Ruby, or Node.js. A "back-end web" framework helps you do things like build APIs, serve HTML files, and handle hundreds of thousands of simultaneous users. Sails is "that kind" of web framework.

Convention over Configuration

Sails accomplishes many of the same goals as other MVC web application frameworks, using many of the same methodologies. This was done on purpose. A consistent approach makes developing apps more predictable and efficient for everybody involved.

Imagine starting a new job at a company building a Sails app (or imagine starting the company, if that's your thing.) If anyone on your team has worked with frameworks like Zend, Laravel, CodeIgniter, Cake, Grails, Django, ASP.NET MVC, or Rails, Sails will feel pretty familiar. Not only that, but they can look at a Sails project and know, generally, how to code up the basic patterns they've implemented over and over again in the past; whether their background is in PHP, Ruby, Java, C#, or Node.js. What about your second app, or your third? Each time you create a new Sails app, you start with a sane, familiar boilerplate that makes you more productive. In many cases, you'll even be able to recycle some of your backend code.


Sails didn't invent this concept-- it's been around for years. Even before the phrase "Convention over Configuration" (or CoC) was popularized by Ruby on Rails, it was a core tenet of the JavaBeans specification and in many ways, a natural lashback against the extremely verbose XML configuration common in traditional Java web frameworks of the late '90s and early 2000s.

Loose Coupling

The days of forcing a one-size-fits-all approach to development are over. We need tools that allow us to pick and choose the components that fit our requirements. In fact, it’s just plain lazy to create things any other way. Sails’s approach is to loosely couple components so that they can be added or subtracted from your app at will.

Node at its core has created a “can do” culture eager to experiment and make things work. Sails embraces this attitude and strives to deliver tools that work around you. The level of automation or magic you want in Sails is directly tied to the time you have for a project and your experience working with Node. Sails is flexible enough to allow you to explore and create when you have the time but also provides automation when you don’t.

Sails accomplishes this loose coupling using plain-old require. No magic, other than the time to craft components that can be part of the whole but don’t need to be present in order for the whole to work. For example, controllers, models, and configuration files are just Node modules. Sails uses some convention to help. Sails picks up on the name UserController.js in the Controllers folder to deduce that this is indeed a user controller. Another example involves policies. So policies allow you to have a bit of code that executes on controller or specific controller action. The cool part is that the configuration file that connects the policy with the controller/action are separate. That means you can write a bunch of different policies and they are completely portable between Sails apps. You can decide later which controller/actions you want to apply them to.

Sails core consists of twenty different hooks: modules that modify the server runtime, adding middleware, binding route listeners, or otherwise attaching additional capabilities to the framework. This gives you access to override or disable every component and configuration parameter in Sails. These hooks are loaded at run-time when Sails starts. You even have the ability to have one-time configuration for your hook itself. This is actually one of the key differentiators between hooks and services.

Another example of loose coupling is configuration files. Need some configuration to be available for your project? No problem. Create a file in the config folder that uses the common module.exports pattern and everything in that module is available for you from the sails global object.

Almost every component of Sails can either be omitted, overwritten, or extended. For example, Sails has a group of tools called blueprints. These blueprints make it really easy to get a project up and running with regard to routes and CRUD operations. But suppose you want to use the read, update, and delete operations but the create action needs some tender loving care. No problem, just build a create action and the other CRUD operations keep working. Your custom action subs in for the blueprint action. It’s just that simple.