CoreOS Container Linux Logo

A container-focused OS that's designed for painless management in large clusters

CoreOS Container Linux developer SDK guide

These are the instructions for building Container Linux itself. By the end of the guide you will build a developer image that you can run under KVM and have tools for making changes to the code.

Container Linux is an open source project. All of the source for Container Linux is available on github. If you find issues with these docs or the code please send a pull request.

Direct questions and suggestions to the IRC channel or mailing list.

Getting started

Let's get set up with an SDK chroot and build a bootable image of Container Linux. The SDK chroot has a full toolchain and isolates the build process from quirks and differences between host OSes. The SDK must be run on an x86-64 Linux machine, the distro should not matter (Ubuntu, Fedora, etc).


System requirements to get started:

  • curl
  • git
  • bzip2
  • gpg
  • sudo

You also need a proper git setup:

git config --global ""
git config --global "Your Name"

NOTE: Do the git configuration as a normal user and not with sudo.

Using Cork

The cork utility, included in the CoreOS mantle project, is used to create and work with an SDK chroot.

First, download the cork utility:

curl -L -o cork
curl -L -o cork.sig

Now, verify the download with the signature:

gpg --keyserver --recv-keys 9CEB8FE6B4F1E9E752F61C82CDDE268EBB729EC7
gpg --verify cork.sig cork

The gpg --verify command should output something like this:

gpg: Signature made Thu 19 Apr 2018 03:33:40 PM PDT
gpg:                using RSA key 9CEB8FE6B4F1E9E752F61C82CDDE268EBB729EC7
gpg: Good signature from "CoreOS Application Signing Key <>" [unknown]
Primary key fingerprint: 18AD 5014 C99E F7E3 BA5F  6CE9 50BD D3E0 FC8A 365E
     Subkey fingerprint: 9CEB 8FE6 B4F1 E9E7 52F6  1C82 CDDE 268E BB72 9EC7

Then proceed with the installation of the cork binary to a location on your path:

chmod +x cork
mkdir -p ~/.local/bin
mv cork ~/.local/bin
export PATH=$PATH:$HOME/.local/bin

You may want to add the PATH export to your shell profile (e.g. .bashrc).

Next, use the cork utility to create a project directory. This will hold all of your git repos and the SDK chroot. A few gigabytes of space will be necessary.

mkdir coreos-sdk
cd coreos-sdk
cork create # This will request root permisions via sudo
cork enter  # This will request root permisions via sudo

Verify you are in the SDK chroot:

$ grep NAME /etc/os-release
NAME="Container Linux by CoreOS"

To leave the SDK chroot, simply run exit.

To use the SDK chroot in the future, run cork enter from the above directory.

Building an image

Set up the chroot

After entering the chroot via cork for the first time, you should set user core's password:


This is the password you will use to log into the console of images built and launched with the SDK.

Then, to create a root filesystem for the amd64-usr build target beneath the directory /build/amd64-usr/:


Build all of the target binary packages:


Render the CoreOS Container Linux image

Build a production image based on the binary packages built above:


After build_image completes, it prints commands for converting the raw bin into a bootable virtual machine. Run the command.


Once you build an image you can launch it with KVM (instructions will print out after runs).

If you encounter errors with KVM, verify that virtualization is supported by your CPU by running egrep '(vmx|svm)' /proc/cpuinfo. The /dev/kvm directory will be in your host OS when virtualization is enabled in the BIOS.

The ./ file can be found in the ~/trunk/src/build/images/amd64-usr/latest directory inside the SDK chroot.

Boot Options

After completes, run ./ -curses to launch a graphical interface to log in to the Container Linux VM.

You could instead use the -nographic option, ./ -nographic, which gives you the ability to switch from the VM to the QEMU monitor console by pressing CTRL+a and then c. To close the Container Linux Guest OS VM, run sudo systemctl poweroff inside the VM.

You could also log in via SSH by running ./ and then running ssh core@ -p 2222 to enter the guest OS. Running without the -p 2222 option will arise a ssh: connect to host port 22: Connection refused or Permission denied (publickey,gssapi-keyex,gssapi-with-mic) warning. Additionally, you can log in via SSH keys or with a different ssh port by running this example ./ -a ~/.ssh/authorized_keys -p 2223 -- -curses. Refer to the Booting with QEMU guide for more information on this usage.

The default login username is core and the password is the one set in the ./set_shared_user_password step of this guide. If you forget your password, you will need to rerun ./set_shared_user_password and then ./build_image again.

Making changes

git and repo

Container Linux is managed by repo, a tool built for the Android project that makes managing a large number of git repositories easier. From the repo announcement blog:

The repo tool uses an XML-based manifest file describing where the upstream repositories are, and how to merge them into a single working checkout. repo will recurse across all the git subtrees and handle uploads, pulls, and other needed items. repo has built-in knowledge of topic branches and makes working with them an essential part of the workflow.

(from the Google Open Source Blog)

You can find the full manual for repo by visiting - Developing.

Updating repo manifests

The repo manifest for Container Linux lives in a git repository in .repo/manifests. If you need to update the manifest edit default.xml in this directory.

repo uses a branch called 'default' to track the upstream branch you specify in repo init, this defaults to 'origin/master'. Keep this in mind when making changes, the origin git repository should not have a 'default' branch.

Building release images

The production images document is unmaintained and out of date, but contains useful pointers as to how official release images are built.

Tips and tricks

We've compiled a list of tips and tricks that can make working with the SDK a bit easier.

Testing images

Mantle is a collection of utilities used in testing and launching SDK images.