Developing Locally with Kalabox

Work locally and deploy to Pantheon using Kalabox.

Kalabox is a Free and Open Source project allows you to quickly create and manage local environments that mirror site environments on Pantheon with the press of a button, including add on services such as Redis and Solr. Kalabox includes both an intuitive GUI and command-line interface, and is powered by Docker under the hood.

Support for Kalabox is provided via their GitHub issue queue.

Visit the Kalabox documentation site for more detailed information on the Kalabox GUI and development tools.

Local Development Training

Install and start using Kalabox with help from Pantheon experts. Check out our custom DevOps training for agencies.


Installation is as simple as grabbing the latest release from and installing it. There are OS specific details in the Kalabox Documentation if necessary.

Authenticate Your Account

Kalabox uses Machine Tokens to authenticate access to your sites on Pantheon. If you already have a working Terminus installation, it will automatically detect and use that token. However, if this is your first time using a token-based integration, setting it up is very quick:

  1. Click the + icon to open the sidebar.
  2. Select Pantheon in the Add Account section.
  3. Generate a new machine token, copy/paste it into Kalabox GUI click Submit.

Your Pantheon account is now authenticated with Kalabox and will appear in the sidebar.

Create Local Environments for Existing Pantheon Sites

  1. Click Add new site or + to open the sidebar, and select your Pantheon user account.
  2. Select a site.
  3. Name your site, pick the environment you'd like to pull from, and click Submit.

    Kalabox add new site

    This process may take several minutes while Kalabox builds the local environment for your site.

Pull Changes from Pantheon into a Local Environment

  1. Click and select Pull on the target application.

    Kalabox add new site

  2. Choose whether to pull database and files, and click Submit.

View Your Local Environment

Click on your site in the Kalabox app. This will open a new browser window or tab, with the address <YOURSITE> While it may appear that you're accessing a remote site, Kalabox is using a remote DNS server to redirect back to your local instance.

Make Changes to Your Site

In addition to changes made from the WordPress or Drupal interface, you can view and edit your site files at ~/Kalabox/<yoursite>/code. You can also click then Terminal to launch your default terminal software in that directory.

Push Changes to Pantheon

  1. Click and select Push on the target application.

    Kalabox add new site

  2. Enter a commit message.

  3. Choose whether to push database and files, and click Submit.

Work Offline With Kalabox

Even though your Kalabox environment is running on your local computer, it uses a remote DNS server to direct your web browser. To work offline, you need to modify your hosts file.

The location of hosts differs between operating systems. On MacOS and Linux, the file is at /etc/hosts. On Windows, it's c:\windows\system32\drivers\etc\hosts (it may be hidden). Add the following lines to hosts:

  • Windows and MacOS    <yoursite>
  • Linux   <yoursite>


Push to Pantheon Fails

Commits that exist on the target Pantheon environment must also exist locally before changes can be pushed. Additionally, uncommitted SFTP changes on Dev or Multidev environments will prevent Kalabox from pushing work to Pantheon. This can be resolved by the following:

Delete or commit outstanding file changes within the target environment (Dev or Multidev), pull changes from Pantheon, then push again.