Container runtime written in Rust
Go to file
github-actions[bot] 646c1034f7
Merge pull request #2380 from containers/dependabot/cargo/winapi-util-0.1.6
2023-09-22 01:23:14 +00:00
.devcontainer Switch codespace from gitpod 2023-08-25 13:23:42 +00:00
.github Extend wait time for auto-merge 2023-08-19 01:51:59 +00:00
crates chore(deps): bump wasmedge-sdk from 0.11.2 to 0.12.1 2023-09-18 01:11:44 +00:00
docs v0.2.0 2023-08-31 11:54:15 +00:00
hack Don't create a file when it already exists when mounting with bind (#2031) 2023-06-11 21:50:53 -07:00
scripts Fix musl test function not parametered correctly 2023-07-11 16:44:31 -07:00
tests Skip the tests related to criu when criu is not found 2023-09-18 12:37:13 +00:00
tools/wasm-sample fix the warns from cargo clippy 2023-02-12 20:15:56 +09:00
.codecov.yml Ignore autogenerated code 2022-01-04 20:12:53 +01:00
.gitignore Add the handly script for kind and youki 2023-05-07 06:03:00 +00:00
.gitmodules Change submodule url to https://.* 2022-11-18 21:30:33 +09:00
.typos.toml exclude the oci-runtime-test from the typos 2023-07-05 15:56:25 -07:00 Add and 2021-06-13 17:56:20 +09:00
Cargo.lock Merge pull request #2380 from containers/dependabot/cargo/winapi-util-0.1.6 2023-09-22 01:23:14 +00:00
Cargo.toml Fix the feature test and turn on in CI (#2060) 2023-06-19 21:21:18 +09:00
LICENSE Change the license from MIT to Apache 2.0 2021-08-13 18:02:15 +09:00 Update Migration Guide for 0.2.0 release 2023-09-01 15:46:17 +05:30 Quick install guide 2023-06-29 12:51:48 +00:00 Add and 2021-06-13 17:56:20 +09:00
Vagrantfile add missing dependencies in Vagrantfile 2023-05-24 17:20:13 +08:00
Vagrantfile.containerd2youki Update the version of containerd used for testing (#1875) 2023-05-03 12:52:03 -07:00
Vagrantfile.root add missing dependencies in Vagrantfile 2023-05-24 17:20:13 +08:00
justfile Add a hack-benchmark recipe 2023-07-31 08:14:44 -07:00
rust-toolchain.toml Rust 1.72 (#2323) 2023-08-29 08:50:15 -07:00

youki: A container runtime in Rust

Discord GitHub contributors Github CI codecov

youki is an implementation of the OCI runtime-spec in Rust, similar to runc.
Your ideas are welcome here.

Quick Install

User Documentation

About the name

youki is pronounced as /joʊki/ or yoh-key. youki is named after the Japanese word 'youki', which means 'a container'. In Japanese language, youki also means 'cheerful', 'merry', or 'hilarious'.


Here is why we are writing a new container runtime in Rust.

  • Rust is one of the best languages to implement the oci-runtime spec. Many very nice container tools are currently written in Go. However, the container runtime requires the use of system calls, which requires a bit of special handling when implemented in Go. This is too tricky (e.g. namespaces(7), fork(2)); with Rust, it's not that tricky. And, unlike in C, Rust provides the benefit of memory safety. While Rust is not yet a major player in the container field, it has the potential to contribute a lot: something this project attempts to exemplify.

  • youki has the potential to be faster and use less memory than runc, and therefore work in environments with tight memory usage requirements. Here is a simple benchmark of a container from creation to deletion.

    Runtime Time (mean ± σ) Range (min … max)
    youki 198.4 ms ± 52.1 ms 97.2 ms … 296.1 ms
    runc 352.3 ms ± 53.3 ms 248.3 ms … 772.2 ms
    crun 153.5 ms ± 21.6 ms 80.9 ms … 196.6 ms
    Details about the benchmark
    • A command used for the benchmark

      hyperfine --prepare 'sudo sync; echo 3 | sudo tee /proc/sys/vm/drop_caches' --warmup 10 --min-runs 100 'sudo ./youki create -b tutorial a && sudo ./youki start a && sudo ./youki delete -f a'
    • Environment

      $ ./youki info
      Version           0.0.1
      Kernel-Release    5.11.0-41-generic
      Kernel-Version    #45-Ubuntu SMP Fri Nov 5 11:37:01 UTC 2021
      Architecture      x86_64
      Operating System  Ubuntu 21.04
      Cores             12
      Total Memory      32025
      Cgroup setup      hybrid
      Cgroup mounts
        blkio           /sys/fs/cgroup/blkio
        cpu             /sys/fs/cgroup/cpu,cpuacct
        cpuacct         /sys/fs/cgroup/cpu,cpuacct
        cpuset          /sys/fs/cgroup/cpuset
        devices         /sys/fs/cgroup/devices
        freezer         /sys/fs/cgroup/freezer
        hugetlb         /sys/fs/cgroup/hugetlb
        memory          /sys/fs/cgroup/memory
        net_cls         /sys/fs/cgroup/net_cls,net_prio
        net_prio        /sys/fs/cgroup/net_cls,net_prio
        perf_event      /sys/fs/cgroup/perf_event
        pids            /sys/fs/cgroup/pids
        unified         /sys/fs/cgroup/unified
      CGroup v2 controllers
        cpu             detached
        cpuset          detached
        hugetlb         detached
        io              detached
        memory          detached
        pids            detached
        device          attached
      Namespaces        enabled
        mount           enabled
        uts             enabled
        ipc             enabled
        user            enabled
        pid             enabled
        network         enabled
        cgroup          enabled
      $ ./youki --version
      youki version 0.0.1
      commit: 0.0.1-0-0be33bf
      $ runc -v
      runc version 1.0.0-rc93
      commit: 12644e614e25b05da6fd08a38ffa0cfe1903fdec
      spec: 1.0.2-dev
      go: go1.13.15
      libseccomp: 2.5.1
      $ crun --version
      crun version
      commit: 4cc7fa1124cce75dc26e12186d9cbeabded2b710
      spec: 1.0.0
  • I have fun implementing this. In fact, this may be the most important.

Related project

Status of youki

youki is not at the practical stage yet. However, it is getting closer to practical use, running with docker and passing all the default tests provided by opencontainers/runtime-tools. youki demo

Feature Description State
Containerd Running via Containerd
Docker Running via Docker
Podman Running via Podman
pivot_root Change the root directory
Mounts Mount files and directories to container
Namespaces Isolation of various resources
Capabilities Limiting root privileges
Cgroups v1 Resource limitations, etc
Cgroups v2 Improved version of v1 Support is complete except for devices. WIP on #230
Systemd cgroup driver Setting up a cgroup using systemd
Seccomp Filtering system calls
Hooks Add custom processing during container creation
Rootless Running a container without root privileges
OCI Compliance Compliance with OCI Runtime Spec 50 out of 50 test cases passing
CRIU Integration Functionality to checkpoint/restore containers Initial checkpoint support as described in #641

Design and implementation of youki

The User and Developer Documentation for youki is hosted at


Getting Started

Local build is only supported on Linux. For other platforms, please use the Vagrantfile that we have prepared. You can also spin up a fully preconfigured development environment in the cloud with gitpod.

Open in Gitpod


  • Rust(See here), edition 2021
  • linux kernel ≥ 5.3


To install just, follow the instruction here.

$ sudo apt-get install    \
      pkg-config          \
      libsystemd-dev      \
      libdbus-glib-1-dev  \
      build-essential     \
      libelf-dev          \
      libseccomp-dev      \
      libclang-dev        \
      glibc-static        \
$ sudo dnf install          \
      pkg-config            \
      systemd-devel         \
      dbus-devel            \
      elfutils-libelf-devel \
      libseccomp-devel      \
      clang-devel           \


git clone
cd youki
just youki-dev # or youki-release
./youki -h # you can get information about youki command



Create and run a container

Let's try to run a container that executes sleep 30 with youki. This tutorial may need root permission.

git clone
cd youki
just youki-dev # or youki-release

mkdir -p tutorial/rootfs
cd tutorial
# use docker to export busybox into the rootfs directory
docker export $(docker create busybox) | tar -C rootfs -xvf -

Then, we need to prepare a configuration file. This file contains metadata and specs for a container, such as the process to run, environment variables to inject, sandboxing features to use, etc.

../youki spec  # will generate a spec file named config.json

We can edit the config.json to add customized behaviors for container. Here, we modify the process field to run sleep 30.

  "process": {
    "args": [
      "sleep", "30"


Then we can explore the lifecycle of a container:

cd ..                                                # go back to the repository root
sudo ./youki create -b tutorial tutorial_container   # create a container with name `tutorial_container`
sudo ./youki state tutorial_container                # you can see the state the container is `created`
sudo ./youki start tutorial_container                # start the container
sudo ./youki list                                    # will show the list of containers, the container is `running`
sudo ./youki delete tutorial_container               # delete the container

Change the command to be executed in config.json and try something other than sleep 30.

Rootless container

youki provides the ability to run containers as non-root user(rootless mode). To run a container in rootless mode, we need to add some extra options in config.json, other steps are same with above:

$ mkdir -p tutorial/rootfs
$ cd tutorial
# use docker to export busybox into the rootfs directory
$ docker export $(docker create busybox) | tar -C rootfs -xvf -

$ ../youki spec --rootless          # will generate a spec file named config.json with rootless mode
## Modify the `args` field as you like

$ ../youki run rootless-container   # will create and run a container with rootless mode


Start the docker daemon.

dockerd --experimental --add-runtime="youki=$(pwd)/youki"

If you get an error like the below, that means your normal Docker daemon is running, and it needs to be stopped. Do that with your init system (i.e., with systemd, run systemctl stop docker, as root if necessary).

failed to start daemon: pid file found, ensure docker is not running or delete /var/run/

Now repeat the command, which should start the docker daemon.

You can use youki in a different terminal to start the container.

docker run -it --rm --runtime youki busybox

Afterwards, you can close the docker daemon process in other the other terminal. To restart normal docker daemon (if you had stopped it before), run:

systemctl start docker # might need root permission

Integration Tests

Go and node-tap are required to run integration tests. See the opencontainers/runtime-tools README for details.

git submodule update --init --recursive
just oci-tests

Setting up Vagrant

You can try youki on platforms other than Linux by using the Vagrantfile we have prepared. We have prepared two environments for vagrant, namely rootless mode and rootful mode

git clone
cd youki

# If you want to develop in rootless mode, and this is the default mode
vagrant up
vagrant ssh

# or if you want to develop in rootful mode
VAGRANT_VAGRANTFILE=Vagrantfile.root vagrant up
VAGRANT_VAGRANTFILE=Vagrantfile.root vagrant ssh

# in virtual machine
cd youki
just youki-dev # or youki-release


We also have an active Discord if you'd like to come and chat with us.


This project welcomes your PR and issues. For example, refactoring, adding features, correcting English, etc. If you need any help, you can contact me on Twitter.

Thanks to all the people who already contributed!