Get Started

Installing and compiling IncludeOS.

Installing IncludeOS on a Mac or Linux computer is relativly straight forward. It does require a few libraries and a compiler. Once installed you can build and launch IncludeOS application locally.

Set custom location and compiler

By default the project is installed to /usr/local/includeos.

However, it is recommended to choose a custom location as well as select the compiler we want clang to find. In this document we assume you install IncludeOS in your home directory, in the folder ~/includeos.

To do this we can edit ~/.bash_profile (mac os) or ~/.bashrc (linux), adding these lines at the end of the file:

    export INCLUDEOS_PREFIX=~/includeos/

This will also crucially make the boot program visible globally, so that you can simply run boot <myservice> inside any service folder.

Install libraries

If you want to install IncludeOS on Mac OS you’ll need a working installation of [brew] so the install script can install its dependencies.

NOTE: The script will install packages.

    $ git clone ""
    $ cd IncludeOS
    $ ./

The script will:

  • Install the required dependencies: curl make clang-3.8 nasm bridge-utils qemu.
  • Create a network bridge called bridge43, for tap-networking.
  • Build IncludeOS with CMake:
    • Download the latest binary release bundle from github together with the required git submodules.
    • Unzip the bundle to the current build directory.
    • Build several tools used with IncludeOS, including vmbuilder, which turns your service into a bootable image.
    • Install everything in $INCLUDEOS_PREFIX/includeos (defaults to /usr/local).

Configuration of your IncludeOS installation can be done inside build/ with ccmake ...

Testing the installation

A successful setup enables you to build and run a virtual machine. There are a few demonstration services in the source folder. If you look in the examples/ folder you see these. If you enter demo_service and type boot --create-bridge . this script will build the service and boot it using [qemu].

    $ cd examples/demo_service
    $ boot --create-bridge .

will build and run this example service. You can visit the service on

More information is available on the wiki.

Writing your first service

  1. Copy the ./seed/service directory to a convenient location like ~/your_service. Then, just start implementing the Service::start function in the Service class, located in your_service/service.cpp (very simple example provided). This function will be called once the OS is up and running.
  2. Update the CMakeLists.txt to specify the name of your project, enable any needed drivers or plugins, etc.


    $ cp -r seed/service ~/my_service
    $ cd ~/my_service
    $ emacs service.cpp
    ... add your code
    $ mkdir build && cd build
    $ cmake ..
    $ make
    $ boot my_service

Take a look at the examples and the tests. These all started out as copies of the same seed.