Installing and Using KoBoToolbox on Your Computer (ADVANCED)

Last Updated: May 19, 2016 11:12AM EDT

‚ÄčThe best way to use KoBoToolbox is on one of the two public instances - (if you work for a humanitarian organization) and (for non-humanitarian users). There is no software to be installed on your computer when using these free public servers. 

Installing KoBoToolbox on your own computer is not necessary and is only recommended if you work in an environment with absolutely no Internet access or if security circumstances require it. To learn about installing the software on your own servers, click here.

Warning: This is still an advanced feature. Although we strive very hard to avoid it, things may break. Please understand that you shouldn't use this in a critical environment without having the technical resources in place to troubleshoot if needed.

Installing KoBoToolbox with Docker

KoBoToolbox can be installed on Linux using our own Docker installation, using the latest code as is available on our public websites. The detailed instructions and the source repository are found on Github. Support for installing with Docker on Mac and Windows is only experimental at this point. For Mac and Windows users please consider installing the old Virtualbox-Vagrant option (see below). 

With Docker you can run a small "mini server" on your local computer. This means that the software is still accessed through the browser but from a "local" address. The installation procedure is similar to running the software through Docker on a server, but significantly easier since the server requires additional configurations.

Installing KoBoToolbox with Vagrant and Virtualbox (outdated)

We have created a snapshot of the tool that can be installed locally. Note that this version is no longer actively maintained. Using Vagrant and Virtualbox you can run a small "mini server" on your local computer. This means that the software is still accessed through the browser but from a "local" address. 
  1. Download and install Vagrant (161 MB) and Virtualbox 4.3 (108 MB)
  2. Download the 'dist-kobo-devel-stable' Github repository branch (30KB) and unzip it to a local computer
  3. Recommended but optional steps:
    • Download the latest pre-built Vagrant box file into your 'dist-kobo-devel-stable' directory 
    • Open a command line terminal, go to the 'dist-kobo-devel-stable' directory and type in
      set VM_BOX=[name of pre-built box file] (for Windows users)
      export VM_BOX=[name of pre-built box file] (for Mac and Linux users)
      Important: Keep this same command line terminal open and use it to execute step 4.
  4. Open a command line terminal in the 'dist-kobo-devel-stable' directory and type in vagrant up. This process is going to take about 5-10 minutes if you followed step 3.

Note: If you didn't follow step 3, the process will download and build all KoBoToolbox components from scratch, which takes about 30-40 minutes and a stable connection to the internet. This may time out or break, depending on your Internet connection.  Once installed, sign in to your KoBoToolbox:

  1. Identify your computer's IP address. This can be done e.g. with the ifconfig command. If you are not connected to a network, you can use "" as your IP address to access KoBo from the computer it's running on.
  2. Open your browser and type in the address "http://[YOUR IP ADDRESS HERE]:8000". You will see the KoBoToolbox login page.
  3. Log in with username: kobo and password: kobo
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found
Our help pages have moved. Please visit