Skip to content
Hypervisor-based Runtime for OCI
Branch: master
Clone or download
Latest commit 10eb687 Jan 9, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
agent agent: fix kata agent SignalProcess ExecId Feb 11, 2018
api move vm.overcommit_memory related code to hyperstart Jan 30, 2018
cli kill shim carefully Jan 9, 2019
design add maintainers rules and list Jun 22, 2017
docs update the kernel path in the docs Dec 22, 2017
driverloader remove vbox driver support Sep 29, 2017
factory use hypervisor.BootConfig for factories' arguements Jun 11, 2017
hack remove protobuf from runv/api/ Dec 9, 2017
hypervisor Fix network performance issue on arm64 for runv Mar 22, 2018
lib Merge pull request #648 from hyperhq/runv-1.0.y Dec 13, 2017
template use hypervisor.BootConfig for factories' arguements Jun 11, 2017
tests cli: add namespace requirements to default spec Feb 11, 2018
vendor update vendor Feb 27, 2018
.gitignore add bats integration tests Aug 18, 2017
.travis.yml add bats integration tests Aug 18, 2017 add maintainers rules and list Jun 22, 2017
Gopkg.lock update vendor Feb 27, 2018
Gopkg.toml update vendor for kata-containers/agent Jan 30, 2018
LICENSE Update LICENSE Mar 21, 2018 build lib/runvxenlight only if xen version is greater than 4.9 Dec 13, 2017
NOTICE add NOTICE file and do not support BSD os Aug 14, 2015
OWNERS add maintainers rules and list Jun 22, 2017 update the kernel path in the docs Dec 22, 2017 portable shell function definition in case /bin/sh is not bash Sep 14, 2015 fix configure file mistake in the last commit of #646 Dec 13, 2017
logo.png add a logo for runV Aug 18, 2017

Build Status


runV is a hypervisor-based runtime for OCI.


runV is compatible with OCI. However, due to the difference between hypervisors and containers, the following sections of OCI don't apply to runV:

  • Namespace
  • Capability
  • Device
  • linux and mount fields in OCI specs are ignored


The current release of runV supports the following hypervisors:

  • KVM (QEMU 2.1 or later)
  • KVM (Kvmtool)
  • Xen (4.5 or later)
  • QEMU without KVM (NOT RECOMMENDED. QEMU 2.1 or later)


The current release of runV supports the following distros:

  • Ubuntu 64bit
    • 15.04 Vivid
    • 14.10 Utopic
    • 14.04 Trusty
  • CentOS 64bit
    • 7.0
    • 6.x (upgrade to QEMU 2.1)
  • Fedora 20-22 64bit
  • Debian 64bit
    • 8.0 jessie
    • 7.x wheezy (upgrade to QEMU 2.1)


# install autoconf automake pkg-config make gcc golang qemu
# optional install device-mapper and device-mapper-devel for device-mapper storage
# optional install xen and xen-devel for xen driver
# optional install libvirt and libvirt-devel for libvirt driver
# note: the above package names might be different in various distros
# create a '' in your GOPATH/src
$ cd $GOPATH/src/
$ git clone
$ cd runv
$ ./
$ ./configure --without-xen
$ make
$ sudo make install


Install qemu

runv by default uses qemu to start virtual machines and makes use of KVM if it is supported. Please make sure qemu is installed on the machine.

Install hyperstart

runv needs hyperstart to provide guest kernel and initrd. By default, it looks for kernel and hyper-initrd.img from /var/lib/hyper/ directory. Build hyperstart and copy them there:

$ git clone
$ cd hyperstart
$ ./ ;./configure ;make
$ mkdir /var/lib/hyper/
$ cp build/hyper-initrd.img build/arch/x86_64/kernel /var/lib/hyper

Creating an OCI Bundle

In order to use runv you must have your container in the format of an OCI bundle. If you have Docker installed you can use its export method to acquire a root filesystem from an existing Docker container.

# create the top most bundle directory
mkdir /containerbundle
cd /containerbundle

# create the rootfs directory
mkdir rootfs

# export busybox via Docker into the rootfs directory
docker export $(docker create busybox) | tar -C rootfs -xvf -

Creating an OCI Container Spec

After a root filesystem is populated you just generate a spec in the format of a config.json file inside your bundle. runv provides a spec command to generate a base template spec that you are then able to edit. To find features and documentation for fields in the spec please refer to the specs repository.

runv spec

runc spec can be also used here for gernerating the config.json for a runv containter, since runv and runc are both OCI compatitible runtime.

Running Containers

The convenience command run will handle creating, starting, and deleting the container after it exits.

# run as root
cd /containerbundle
runv --kernel /path/to/kernel --initrd /path/to/initrd.img run mycontainer
# If you used the unmodified `runv spec` template this should give you a `sh` session inside the container.
$ ps aux
root         1  0.0  0.1   4352   232 ttyS0    S+   05:54   0:00 /init
root         2  0.0  0.5   4448   632 pts/0    Ss   05:54   0:00 sh
root         4  0.0  1.6  15572  2032 pts/0    R+   05:57   0:00 ps aux

The arguemnts --kernel /path/to/kernel and --initrd /path/to/initrd.img can be omitted. In this case, /var/lib/hyper/kernel and /var/lib/hyper/hyper-initrd.img will be used by runv.

A container can be also be run via using the specs lifecycle operations. Such as runv create mycontainer, runv start mycontainer and runv delete mycontainer. This gives you more power over how the container is created and managed while it is running.

Run it with docker

runv is a runtime implementation of OCI runtime and its command line is highly compatible with the 1.0.0-rc3(keeping updated with the newest released runc). But it is still under development and uncompleted.

runV provides a detailed walk-though to integrate with latest versions of docker and containerd.

Quick example (requires 17.06.1-ce that talks runc-1.0.0-rc3 command line):

Configure docker to use runV as the default runtime.

$cat /etc/docker/daemon.json
  "default-runtime": "runv",
  "runtimes": {
    "runv": {
      "path": "runv"

Start docker, pull and create busybox container.

$sudo systemctl start docker
$docker pull busybox
Using default tag: latest
latest: Pulling from library/busybox
Digest: sha256:2605a2c4875ce5eb27a9f7403263190cd1af31e48a2044d400320548356251c4
Status: Image is up to date for busybox:latest
$docker run --rm -it busybox
/ # ls
bin   dev   etc   home  lib   proc  root  sys   tmp   usr   var
/ # exit
You can’t perform that action at this time.