View our GitHub

Please visit sails-docs on GitHub to view documentation on your mobile device.

Edit Page

Miscellaneous (sails.config.*)

For a conceptual overview of configuration in Sails, see

This page is a quick reference of assorted configuration topics that don't fit elsewhere, namely top-level properties on the sails.config object. Many of these properties are best set on a per-environment basis, or in your config/local.js. To set them globally for your app, create a new file in the config folder (e.g. config/misc.js) and add them there.


The port setting determines which TCP port your app will be deployed on. Ports are a transport-layer concept designed to allow many different networking applications to run at the same time on a single computer.

By default, if it’s set, Sails uses the PORT environment variable. Otherwise it falls back to port 1337. In production, you’ll probably want to change this setting to 80 (http://) or 443 (https://) if you have an SSL certificate.

More about ports:


By default, Sails will assume localhost as the host that will be listening for incoming requests. This will work in the majority of hosting environments you encounter, but in some cases (OpenShift being one example) you'll need to explicitly declare the host name of your Sails app. Setting explicitHost tells Sails to listen for requests on that host instead of localhost.

sails.config.proxyHost and sails.config.proxyPort

If your site will ultimately be served by a proxy, you may want to set proxyHost to ensure that calls to sails.getBaseurl() return the expected host. For example, if you deploy a Sails app on, the ultimate URL for your site will be something like If you were to use sails.getBaseurl() to construct a URL in your app code, however, it would return something like http://localhost:8080. Using proxyHost and proxyPort allow you to specify the host name and port of the proxy server that will be serving your app. This ensure that any links created using sails.getBaseurl() are correct.



The NODE_ENV environment variable is usually a better idea than setting sails.config.environment manually, since it's a generic Node convention. The sails.config.environment setting may be deprecated in Sails v1.0.

The runtime “environment” of your Sails app is either ‘development’ or ‘production’.

In development, your Sails app will go out of its way to help you (for instance you will receive more descriptive error and debugging output).

In production, Sails configures itself (and its dependencies) to optimize performance. You should always put your app in production mode before you deploy it to a server -- this helps ensure that your Sails app remains stable, performant, and scalable.

By default, Sails sets its environment using the NODE_ENV environment variable. If NODE_ENV is not set, Sails will run in the ‘development’ environment.


Set a global timeout for Sails hooks, in milliseconds. Sails will give up trying to lift if any hook takes longer than this to load. Defaults to 20000.


By default, convenience functions badRequest, forbidden, notFound, and serverError will clear the response body when the environment is "production". This behavior may be undesirable in certain cases, such as exposing underlying Waterline validation errors to clients while responding through badRequest.

Set keepResponseErrors to true to ensure Sails preserves the response body for these functions.


Use this config to set up basic SSL server options, or to indicate that you will be specifying more advanced options in sails.config.http.serverOptions.

If sails.config.ssl is set, it should be an object with key and cert keys or a pfx key. The presence of those options indicates to Sails that your app should be lifted with an HTTPS server. If your app requires a more complex SSL setup (for example by using SNICallback), set cert and key to true and specify your advanced options in sails.config.http.serverOptions.

Is something missing?

If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the sails-docs repo. Once we merge it, the changes will be reflected on the website the next time it is deployed.


We wrote a book!

Get early access to the book
with promotion code: mcneildoc

Get the Book