Boxfuse supports apps written in JavaScript or any other language and packaged as an .tgz file running on Node.js 5.7 or newer.

Get Started

If you haven't already, start by following Node.js & Boxfuse tutorial that will get you up and running in 5-10 minutes.


Applications should be packaged using with all dependencies marked as bundledDependencies. The easiest way to achieve this is to use npm-bundle.

Start by installing npm-bundle:

> npm install -g npm-bundle

Make sure you shrinkwrap your project (this will create a npm-shrinkwrap.json file):

> npm shrinkwrap

Then simply create the tgz in the directory containing your package.json:

> npm-bundle

And finally fuse and run the Boxfuse image from that same directory:

> boxfuse run

Node.js version

By default Boxfuse attempts to autodetect the Node.js version from the engines section in package.json.

If no fixed version is specified, Boxfuse falls back to the latest Node.js version (Current branch).

If you want to switch to an LTS release or simply an older version, you override this by using the -components.nodejs configuration setting:

> boxfuse run my-app-1.0.tgz -components.nodejs=5.9.1

To find out which Node.js versions are available from the Boxfuse Inventory you can simply issue:

> boxfuse inventory nodejs


By Boxfuse configures your application's http port as well as the PORT environment variable to 80. If your application has been generated by express it should pick this up automatically. Otherwise you need to adjust either your application or the Boxfuse ports configuration to match.


Database auto-provisioning

When using the Boxfuse database auto-provisioning support, Boxfuse automatically exposes your database's host, port, name, user and password for the current environment as environment variables.

If your app includes the pg or mysql npm module, Boxfuse will automatically provision the necessary PostgreSQL or MySQL database in each environment.

Using an existing database

To disable database auto-provisioning and use an existing database set db.type to none when creating your app.


To connect to your MySQL database you can use the following code:

var mysql = require('mysql');
var connection = mysql.createConnection({
  host     : process.env.BOXFUSE_DATABASE_HOST,
  port     : process.env.BOXFUSE_DATABASE_PORT,
  user     : process.env.BOXFUSE_DATABASE_USER,
  password : process.env.BOXFUSE_DATABASE_PASSWORD,
  database : process.env.BOXFUSE_DATABASE_NAME,
  ssl      : process.env.BOXFUSE_DATABASE_CA_CERT,
  charset  : 'utf8mb4_unicode_ci',
  timezone : 'utc'
// Execute query

This also automatically ensures that all connections to RDS MySQL use TLS (SSL).


To connect to your PostgreSQL database you can use the following code:

var pg = require('pg');
var fs = require('fs');

var connectionInfo = {
  host     : process.env.BOXFUSE_DATABASE_HOST,
  port     : process.env.BOXFUSE_DATABASE_PORT,
  user     : process.env.BOXFUSE_DATABASE_USER,
  password : process.env.BOXFUSE_DATABASE_PASSWORD,
  database : process.env.BOXFUSE_DATABASE_NAME
if (process.env.BOXFUSE_DATABASE_CA_CERT) {
  connectionInfo.ssl = {
    ca: [fs.readFileSync(process.env.BOXFUSE_DATABASE_CA_CERT, 'utf8')]

var client = new pg.Client(connectionInfo);
client.connect(function(err) {
  // Execute query

This also automatically ensures that all connections to RDS PostgreSQL use TLS (SSL).

TLS (SSL) Certificates / HTTPS

To expose your app via HTTPS make sure you have a custom domain configured for the environment where you want to run it. Also make sure that you have obtained a valid TLS (SSL) certificate and that your app has been created with app.type set to load-balanced and tls.type set to acm (AWS Certificate Manager).

To listen to the HTTPS port you can use the following code:

var https = require('https');
var fs = require('fs');

var server = https.createServer({
    key: fs.readFileSync('/app-config/boxfuse-selfsigned-key.pem'),
    cert: fs.readFileSync('/app-config/boxfuse-selfsigned-cert.pem'),
    requestCert: false,
    rejectUnauthorized: false
}, app);

This will ensure that all network traffic between the ELB and your instances will be encrypted as well.

Root Certificates

Boxfuse uses the same root certificate bundle as the latest version of Firefox. Additionally Boxfuse also includes the root certificates for Amazon RDS, so you can connect securely to RDS databases out of the box.

Temporary Files

Boxfuse configures the JVM to use /tmp as the directory to store temporary files and provisions 1 GB of space by default.

To increase this (up to a maximum of 16 TB), simply set the tmp configuration setting to the number of GB of temp space you need. To prevent Boxfuse from provisioning any temp space set tmp to 0.


Remote debugging (including hot-code replace) with your favorite IDE is fully supported. Details and setup instructions on our debugging page.

Live Reloading

In the dev environment, you can reload changes live by running Boxfuse at the root of your Node.js project with -live:

> npm install
> boxfuse run -live

Also check out our blog post on how to reload Node.js application live on VirtualBox with Boxfuse.

Time Zone

By default all Boxfuse instance use the UTC time zone.

We don't recommend changing this as this greatly simplifies time zone issues in machine to machine communication and cleanly relegates all time zones related aspects to a pure presentation layer concern.

If however you still do want to change this, you can override the default time zone of the instance using the TZ environment variable. For example to change the time zone of your instance to America/Los_Angeles you would do so like this:

> boxfuse fuse -envvars.TZ=America/Los_Angeles

Native binaries and libs

Some Node.js applications also depend on native Linux x64 binaries and libs to do their work. Boxfuse makes it easy to integrate them into your image.

Simply place your binaries under /native/bin inside your tgz and Boxfuse will automatically add them to the PATH at runtime in your instances.

If those binaries also depend on additional shared libraries beyond the C library, place the .so files of your libraries under /native/lib inside your tgz and Boxfuse will automatically add them to the LD_LIBRARY_PATH at runtime in your instances.


To list all the shared libraries your Linux x64 binary requires, you can use the following command on a Linux system:

$ ldd -v my-native-binary

This effectively means the native binaries and libs should be under a native directory inside your application:


Linux Kernel Tuning (experts only)

Kernel arguments

To tune the arguments passed Linux kernel from the bootloader, simply pass them using the -linux.args setting when fusing your image.


If you need to tune the Linux kernel running in your instance, simply place a sysctl.conf file at the root inside your tgz file. This effectively means it should be in the root directory of your application:


You can then for example tune the maximum number of file descriptors by simply including the following in sysctl.conf:

fs.file-max = 131072

Boxfuse will then automatically configure the Linux kernel to use these settings.

ELF64 Binaries