The BentoBox2 Developer Hub

Welcome to the BentoBox2 developer hub. You'll find comprehensive guides and documentation to help you start working with BentoBox2 as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Developer Documentation

Environment Setup

Environment Setup Workflow is Under Development

For developer access and feature updates please email


Developers who wish to work on a theme's templates, assets (CSS, JavaScript, etc) and configuration files can do so locally with the BentoDev package! (This is an update from the preview FTP server as we have moved to AWS).

Theme Structure

BentoBox site themes are organized in three main folders and one config file:

Contains all of the template files that render your html. The templating language used is Jinja2.
Learn more about Template Basics

Contains all of the .json files that let you customize the BentoBox CMS experience for the CMS User.
Learn more about Template Configuration
Learn more about Box Configuration
Learn more about Wireframe Configuration

Contains all of the static assets (js/css/images) that are used in your site theme.
Learn more about Assets

Contains the core site theme configuration options such as Navs.
Learn more about Theme Options

Get Started With Our Boilerplate Theme

BentoDev - Theme Editing Tool

The BentoDev tool acts as a local web server. Each environment (production, local), reads theme files from a different directory, but the data is shared between them. You can develop and test your theme on with BentoDev on your local computer without having to worry about affecting production, however any changes to the underlying data made using the CMS will affect both environments.

Install BentoDev

NOTE: This package is currently only supported on POSIX (MacOS, Linux, etc) systems. For those on Windows it is recommended to create a new Vagrant box before installing.

It is recommended to install BentoDev on a separate Python 3 virtual environment.

# ex. python3 -m venv <path/to/dir>
$ python3 -m venv venv

# Then activate the virtualenv
$ source venv/bin/activate

After ensuring one is on the correct Python 3 environment simply pip install:

$ pip install bentodev

The current version is 1.7! If an older version is installed from your pip cache, please specify the version with '==<version_number>'


Upon using BentoDev for the first time you will be prompted to use add your BentoBox account.

You may also be asked for a password to get a remote token for your session.

Cloning Themes

By using the command bentodev list or bentodev start you will see the list of available Accounts and their current associated theme.

If you do not see any Accounts/Themes you need to create an Account that is associated to your User through the BentoBox website.

To work on an Account's theme you must first clone the theme. To do so use:

$ bentodev clone <theme_name>

You may be prompted to connect your GitHub account to BentoBox if you have not done so previously.

The theme will then be cloned to the ~/bentodev/sites/<theme_name> folder, where you can push edits with standard git commands.

Working on Themes

Once a theme has been cloned you can then run local server that will handle making requests to BentoBox.

$ bentodev start <account_name>

You should then see the server run, where you can connect at localhost:5000

For further BentoDev documentation please refer to the GitHub page.

Version Control and Deployment

Changing or updating a theme is done through GitHub. All updates made to a theme can then be tracked and committed through standard git tools.
When you commit and push, all of your changes are automatically deployed on the BentoBox servers!

Link your GitHub account to BentoBox by going to your "Developer Settings" page after logging in. BentoDev will also walk you through connecting your GitHub if you have not done so.

Environment Setup