The boxfile.yml is a yaml config file housed in the root of your project that defines what components should exist in your app and all configuration related to your app’s deployment and infrastructure. It allows you to custom-configure your app's environment to your project's specific needs.

Important Things to Know About the Boxfile

  • Boxfiles are required to use Nanobox.
  • Your boxfile must be named boxfile.yml in order to be recognized.
  • The boxfile.yml must be placed at the root of your project's repo.
  • The boxfile must be valid yaml markup. You can brush up on your yaml at or check your syntax at
  • In a local app, application components are created and destroyed by adding and removing them from your boxfile.yml. In live apps, components can only be removed through your dashboard.

Sample Boxfile

  engine: ruby
    runtime: ruby-2.2
    - vendor

    - 'bundle exec rake fix-yaml'
  start: 'bundle exec puma -c config/puma.conf'
      - usr/uploads
  start: 'ruby workers/image_processor.rb'
      - usr/uploads

  image: nanobox/postgresql:9.5
  image: nanobox/unfs:0.9

  image: nanobox/redis:3.0

The Boxfile Structure

Your app is made up of components. A component is a piece of your app's infrastructure tasked with a specific function. Each component is configured separately in the Boxfile.

Yaml is used in the Boxfile because of its simplicity and clarity when defining relationships between data. A component's configuration is indented and nested under the component ID. Each level and relationship of data is defined by indentation.

Boxfile Structure #<-------------------- Component ID
  start: 'rails s'          #|
  network-dirs:             #|-- Component Settings           #|
      - usr/uploads         #|

data.mysql: #<------------------ Component ID
  image: nanobox/mysql:5.6  #|
  config:                   #|-- Component Settings
    event_scheduler: 'Off'  #|

Things to Note About yaml

  • Yaml is very picky about indentation. Indentation is what is used to define the relationship structure of information in your Boxfile.
  • Tabs are not valid yaml. All indentation should be done using double spaces.

Component IDs

Every component in your app has a component ID which consists of two parts:

Component IDs must be unique.

IMPORTANT: Component IDs Cannot be Changed

Component IDs cannot be changed once a boxfile is deployed and the components are created. If they are changed, they will be recognized as new components.

Component IDs

# Pattern

# Examples

Component Types

There are three types of components:

  • web: A code component with publicly accessible ports.
  • worker: A backend code component with no publicly accessible ports.
  • data: A component that houses data of some sort.

Sections of the Boxfile

Boxfiles consist of a handful of sections or "nodes": run.config, deploy.config, dev, web, worker, data. These are covered in detail in the next few docs, but here are some quick descriptions:

run.config - Defines the build, environment, and configuration for web and worker components.

deploy.config - Defines deploy hooks and possible code transformations.

web - Defines settings unique to each web component.

worker - Defines settings unique to each worker component.

data - Defines settings unique to a specific data component.

Reach out to and we'll try to help.