Developing Locally with Kalabox
Work locally and deploy to Pantheon using Kalabox.
Active development for Kalabox has been halted in favor of its successor, Lando. For more details, refer to Lando's documentation.
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.
Install and start using Kalabox with help from Pantheon experts. Check out our custom DevOps training for agencies.
Kalabox requires ports
8160. If you're running another local web server on those ports, it will interfere with Kalabox's ability to function.
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:
- Click the + icon to open the sidebar.
- Select Pantheon in the Add Account section.
- 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
- Click Add new site or + to open the sidebar, and select your Pantheon user account.
- Select a site.
Name your site, pick the environment you'd like to pull from, and click Submit.
This process may take several minutes while Kalabox builds the local environment for your site.
Pull Changes from Pantheon into a Local Environment
Click and select Pull on the target application.
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>.kbox.site. 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.
If your site won't load, it may be due to local network restrictions on DNS rebinding (some open-source routing software like DD-WRT does this by default). If you can't or don't want to remove this restriction, follow the steps for working offline.
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
Click and select Push on the target application.
Enter a commit message.
- 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
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
Windows and MacOS
Plugins that pull data from external sources may not load or display unpredictable behavior when working offline.
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.