Capstan, a tool for packaging and running your application on OSv.
Clone or download
Pull request Compare This branch is 220 commits ahead of cloudius-systems:master.
miha-plesko Merge pull request #103 from wkozaczuk/fix_yaml_time2
Update unit tests to handle quoted timestamps
Latest commit 5af44b4 Sep 18, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
Documentation Added filesystems documentation Sep 14, 2018
Godeps Stop using in favor of Sep 27, 2017
cmd Update unit tests to handle quoted timestamps Sep 18, 2018
core Update unit tests to handle quoted timestamps Sep 18, 2018
cpio Update copyright information Mar 14, 2017
hypervisor Merge pull request #77 from miha-plesko/default-type-to-threads Jan 4, 2018
image Update namespace to forked Capstan's own github repo Dec 12, 2016
nat Clean up port forwarding code Mar 21, 2014
provider/openstack Refactor logic that picks optimal flavor Mar 15, 2017
runtime Add Python runtime to runtime list Jan 4, 2018
scripts Shift version to v0.3.0 in download script Jan 30, 2018
test Create volumes with Capstan Dec 11, 2017
testing Create volumes with Capstan Dec 11, 2017
util Add support to compose OSv images with ROFS (Read-Only Filesystem) fi… Sep 14, 2018
.gitignore Make documentation user-oriented Jan 6, 2017
.gitreview Rename attribute 'vmargs' to 'jvmargs' inside meta/run.yaml Nov 25, 2016
.travis.yml Travis test also go version 1.9 Jan 24, 2018
LICENSE Update copyright information Mar 14, 2017 Linked filesystem documentation to main page Sep 14, 2018
capstan.go Add support to compose OSv images with ROFS (Read-Only Filesystem) fi… Sep 14, 2018
capstan_test.go Add 'platform' column to the output of `capstan images` Sep 27, 2017
install Update installation script to set version properly Jan 6, 2017
install.bat Update installation script to set version properly Jan 6, 2017
make-dist Update scripts to version v0.2.0 Apr 11, 2017


This is an upgraded version of the original Capstan and is maintained by MIKELANGELO consortium. Although it is still possible, joining this repository with the original Capstan is not very likely. We're looking towards the first stable release at the moment.

Capstan is a command-line tool for rapidly running your application on OSv unikernel. It focuses on improving user experience during building the unikernel and attempts to support not only a variety of runtimes (C, C++, Java, Node.js etc.), but also a variety of ready-to-run applications (Hadoop HDFS, MySQL, SimpleFOAM etc.).


Buildning unikernels is generally a nightmare! It is a non-trivial task that requires deep knowledge of unikernel implementation. It depends on numerous installation tools and takes somewhat 10 minutes to prepare each unikernel once configured correctly. But an application-oriented developer is not willing to take a load of new knowledge about unikerel specifics, nor wait long minutes to compile! And that's where Capstan comes in.

Capstan tends to be a tool that one configures with application-oriented settings (Where is application entry point? What environment variables to pass? etc.) and then runs a command or two to quickly boot up a new unikernel with application. Measured in seconds.

To achieve this, Capstan uses precompiled artefacts: precompiled OSv kernel, precompiled Java runtime, precompiled MySQL, and many more. All you have to do is to name what precompiled packages you want to have available in your unikernel and that's it.


Capstan is designed to prepare and run OSv unikernel for you. With Capstan it is possible to:

  • prepare OSv unikernel without compiling anything but your application, in seconds
  • use any precompiled package from the MIKELANGELO package repository, or a combination thereof
  • set arbitrary size of the target unikernel filesystem
  • run OSv unikernel using one of the supported providers

But Capstan is not a magic tool that could solve all the problems for you. Capstan does not:

  • compile your application. If you have Java application, you need to use javac compiler and compile the application yourself prior using Capstan tool!
  • inspect your application. Capstan does nothing with your application but copies it into the unikernel
  • overcome OSv unikernel limits. Consult OSv documentation about what these limits are since they all still apply. Most notably, you can only run single process inside unikernel (forks are forbidden).

Getting started

Capstan can be installed using precompiled binary or compiled from source. Step-by-step Capstan Installation Guide

Using Capstan is rather simple: open up your project directory and create Capstan configuration files there:

$ capstan package init --name {name} --title {title} --author {author}
$ capstan runtime init --runtime {runtime}
# edit meta/run.yaml to match your application structure

Being in project root directory, then use Capstan command to create unikernel (consult CLI Reference for a list of available arguments):

$ capstan package compose {unikernel-name}

At this point, you have your unikernel built. It contains all your project files plus all the precompiled artefacts that you asked for. In other words, the unikernel contains everything and is ready to be started! As you might have expected, there is Capstan command to run unikernel for you (using KVM/QEMU hipervisor):

$ capstan run {unikernel-name}

Congratulations, your unikernel is up-and-running! Press CTRL + C to stop it.



Capstan is distributed under the 3-clause BSD license.


This code has been developed within the MIKELANGELO project (no. 645402), started in January 2015, and co-funded by the European Commission under the H2020-ICT-07-2014: Advanced Cloud Infrastructures and Services programme.