Lightweight Linux for Podman
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

boot2podman logo


Boot2podman is a lightweight Linux distribution made specifically to run Linux containers. It runs completely from RAM, is a ~90MB download.


  • Recent Linux Kernel, Podman / Buildah pre-installed and ready-to-use
  • Tools operate on Open Container Initiative (OCI) images and containers.
  • Container persistence via disk automount on /var/lib/containers
  • SSH keys persistence via disk automount (user keys and host keys)


  • Linux 4.14, with support for cgroupfsand overlayfs configured
  • Podman and its dependencies like: runc, conmon, cni-plugins
  • Varlink support for running remotely (being tunneled over SSH)
  • Buildah support for building container images without daemon


Podman is a command line tool that allows for full management of a container's lifecycle from creation through removal. It supports multiple image formats including both the Docker and OCI image formats. Support for pods is provided allowing pods to manage groups of containers together.


Varlink is an interface description format and protocol that aims to make services accessible to both humans and machines in the simplest feasible way. A varlink interface has a reverse-domain name and specifies which methods the interface implements. Each method has named and typed input and output parameters.


The Buildah project provides a command line tool that be used to create an OCI or traditional Docker image format image and to then build a working container from the image. The container can be mounted and modified and then an image can be saved based on the updated container.


Skopeo is a command line tool that performs a variety of operations on container images and image repositories. Skopeo allows you to inspect an image showing its layers without requiring that the image be pulled. Skopeo also allows you to copy and delete an image from a repository.

For more details on the project relationship, see the Container Tools Guide.


ISO can be found in:

Note that if you use podman-machine, it will download the ISO automatically...

Getting started

Please note that you should run podman and buildah using sudo!

In order to connect to the varlink socket (io.podman), you need root.


Containers created with the root user (sudo) are persisted automatically.

If you want to save the tc home directory, use the home=sda1 bootcode.


For now you need to mount the CD-ROM image (ISO) as IDE, not as SATA.

There is currently no support for the VirtualBox Guest Additions (vboxsf).


The default memory allocation (128 MiB) is too small to load everything:

qemu-system-x86_64 -enable-kvm -m 512 -cdrom boot2podman.iso

Sample session

Here showing a simple login session, from an early development version:

screenshot logo


The boot2podman logo is based on the original podman logo and the Montserrat font.

The text logo is based on and figlet -f ascii12 podman.


Currently based on CorePure64-9.0.iso, but with a custom kernel (4.14.10 -> 4.14.93)

We need support for cgroupfs (including "memory") and for overlayfs (on ext4).


We install the required go compiler environment by building from source code.

Then we install podman and other dependencies by building from source code.

  • runc
  • conmon
  • cni-plugins
  • cgroupfs-mount

The varlink command line tool can be installed by building from source code.

Support for running containers as a non-root user by building from source code.

We can also add buildah and its dependencies, by building from source code.

Optionally also skopeo for remote operations, by building from source code.


It is also possible to run the build commands (detailed above) using containers.

Note that you need to use tce-load -wic, if not running privileged (mount).


Here are the binary packages that are produced, after building from source code.


These packages are used for building:

* total size, including dependencies (see .tree and .dep)


These packages are used at runtime:

These .tcz files are bundled with the kernel in a initramfs, as per remastering TC.


The software does not work after installation, without some mandatory registries and policy config done.


registries = ['', '']

registries = []

#blocked (docker only)
registries = []


    "default": [
            "type": "insecureAcceptAnything"
                    "": [{"type":"insecureAcceptAnything"}]


# This is the default signature write location for docker registries.
  # sigstore: file:///var/lib/atomic/sigstore
  sigstore-staging: file:///var/lib/atomic/sigstore

We need to make sure to use "cgroupfs" (not systemd) and to disable "pivot_root" (to run under tmpfs).


# CGroup Manager - valid values are "systemd" and "cgroupfs"
cgroup_manager = "cgroupfs"

# Whether to use chroot instead of pivot_root in the runtime
no_pivot_root = true

Location of the configuration is currently hard-coded to /etc/containers, so it is not included in tcz...

Some information is currently not configurable, so it needs to be patched in to the source code directly.


Sample configuration, for /usr/local/etc/cni/net.d:

  • bridge
  • portmap
  • loopback

Example config files can be found at these locations:

Persist data

Boot2podman uses Tiny Core Linux, which runs from RAM and so does not persist filesystem changes by default.

When you run podman-machine create box, the tool auto-creates a disk that will be automounted and used to persist your docker data in /var/lib/containers and /var/lib/boot2podman. This virtual disk will be removed when you run podman-machine delete box. It will also persist the SSH keys of the machine. Changes outside of these directories will be lost after powering down or restarting the VM.

If you are not using the Podman Machine management tool, you can create an ext4 formatted partition with the label boot2podman-data (mkfs.ext4 -L boot2podman-data /dev/sdX5) to your VM or host, and Boot2podman will automount it on /mnt/sdX and then softlink /mnt/sdX/var/lib/containers to /var/lib/containers.


Boot2podman is inspired by Boot2Docker, which is a similar solution but for another popular container runtime.