Skip to content
@wolfi-dev

Wolfi

Wolfi OS GitHub home.

wolfi logo wolfi logo

Wolfi OS

Wolfi is the first community Linux (un)distribution declaratively built for creating a secure base layer for your containers!

Wolfi is a community Linux OS designed for the container and cloud-native era. Chainguard started the Wolfi project to enable building Chainguard Images, our collection of curated distroless images that meet the requirements of a secure software supply chain. This required a Linux distribution with components at the appropriate granularity and with support for glibc.

Wolfi is a stripped-down distro designed for the cloud-native era. It doesn't have a kernel of its own, instead relying on the environment (such as the container runtime) to provide one. This separation of concerns in Wolfi means it is adaptable to a range of environments.

Wolfi Features

Wolfi, whose name was inspired by the world's smallest octopus, has some key features that differentiates it from other distributions that focus on container/cloud-native environments:

  • Provides a high-quality, build-time SBOM as standard for all packages
  • Packages are designed to be granular and independent, to support minimal images
  • Uses the proven and reliable apk package format
  • Fully declarative and reproducible build system
  • Designed to support glibc

Where's the Source?

  • os contains the core Wolfi OS repository.

Wolfi Community

The community repo contains full details of our regular community calls, support forums and social media presence.

Resource Details, Links, etc.
Notes View our notes from community meetings
YouTube View our playlist of recorded community meetings
Twitter / X @wolfi_os
Slack #apko channel on Kubernetes Slack
Forum See GitHub Discussions

Get Started

To get you up and running with Wolfi, let's go over a quick demo where you can create an image from a Dockerfile.

We'll use a "Hello, World" style Python program to demonstrate:

def main():
    print("Hello, Wolfi!")

if __name__ == "__main__":
    main()

Within the same directory, you can create the Dockerfile. This Dockerfile will set up the WORKDIR, and copy relevant files. It will also define the entry point that will be executed when we run this image with docker run. We are using the wolfi-base image to build a Python image from scratch, using Wolfi apks. The final image runs using the unprivileged nonroot user.

FROM cgr.dev/chainguard/wolfi-base

ARG version=3.11
WORKDIR /app

RUN apk add python-${version} && chown -R nonroot.nonroot /app/

USER nonroot

COPY  hello_wolfi.py /app/
ENTRYPOINT [ "python", "hello_wolfi.py" ]

This Dockerfile uses a variable called version to define which Python version is going to be installed on the resulting image. You can change this to one of the available Python versions on the wolfi-dev/os repository.

From here, you can build and run your image. If you run into issues with the build step, try using sudo.

docker build . -t hellowolfi
docker run --rm hellowolfi

You should receive the following output:

Hello, Wolfi!

For more guidance, you can check out a full tutorial on Creating Wolfi Images with Dockerfiles, or alternately use apko to build a distroless image with only the packages you need, by reviewing a Getting Started with apko tutorial.

FAQ

What is Wolfi and how does it compare to Alpine?

Wolfi is a Linux undistro designed from the ground up to support newer computing paradigms such as containers. Although Wolfi has a few similar design principles as Alpine (such as using apk), it is a different distribution that is focused on supply chain security. Unlike Alpine, Wolfi does not currently build its own Linux kernel, instead relying on the host environment (e.g. a container runtime) to provide one.

Is Wolfi free to use?

Yes, Wolfi is free and will always be.

Can I mix packages from Alpine repositories into a Wolfi-based image?

No, it’s not possible to mix Alpine apks with Wolfi apks. If your image requires dependencies that are currently only available for Alpine, you might consider opening a new issue in the wolfi-os repository to suggest the new package addition, or use melange to build a custom apk for your image.

Can I use Wolfi on the Desktop?

No. Desktop distributions require additional software that is out of scope for Wolfi's roadmap.

Who maintains Wolfi?

Wolfi was created and is currently maintained by Chainguard.

What are the plans for long-term Wolfi governance?

We intend for Wolfi to be a community-driven project, which means over time it will have multi-vendor governance and maintainers. For now we're focused on building the project and community, and will revisit this in several months when a community has formed.

Where can I get security feeds for Wolfi?

See SECURITY.md for information about reporting security incidents concerning and consuming security data about Wolfi.

Where can I ask questions or learn more about using Wolfi?

We have a monthly community call on the 1st Wednesday of every month! Join the next meeting by following Wolfi’s public calendar, or submit your question to our GitHub Community discussions forum.

Pinned Loading

  1. os os Public

    Main package repository for production Wolfi images

    Shell 829 262

Repositories

Showing 10 of 16 repositories
  • advisories Public

    Security advisory data for Wolfi

    wolfi-dev/advisories’s past year of commit activity
    Shell 13 Apache-2.0 60 10 28 Updated Dec 5, 2024
  • os Public

    Main package repository for production Wolfi images

    wolfi-dev/os’s past year of commit activity
    Shell 829 262 168 299 Updated Dec 5, 2024
  • actions Public

    A collection of reusable Github Actions workflows.

    wolfi-dev/actions’s past year of commit activity
    5 Apache-2.0 8 1 0 Updated Dec 5, 2024
  • wolfictl Public

    A CLI used to work with the Wolfi OSS project

    wolfi-dev/wolfictl’s past year of commit activity
    Go 57 Apache-2.0 55 43 (1 issue needs help) 31 Updated Dec 4, 2024
  • tools Public

    Various tools, images, etc. to support the Wolfi OSS project

    wolfi-dev/tools’s past year of commit activity
    HCL 19 Apache-2.0 19 4 1 Updated Nov 22, 2024
  • .github Public

    Wolfi Organization README

    wolfi-dev/.github’s past year of commit activity
    5 10 0 0 Updated Nov 22, 2024
  • wolfi-act Public

    Dynamic GitHub Actions from Wolfi packages

    wolfi-dev/wolfi-act’s past year of commit activity
    41 Apache-2.0 4 2 0 Updated May 13, 2024
  • community Public

    Documents and tools powering the Wolfi OS community

    wolfi-dev/community’s past year of commit activity
    17 Apache-2.0 3 2 0 Updated Mar 27, 2024
  • bootstrap-stage3 Public archive

    Stage3 bootstrap for Wolfi

    wolfi-dev/bootstrap-stage3’s past year of commit activity
    Makefile 5 10 0 3 Updated Feb 22, 2024
  • secdb Public archive

    Tool for generating Wolfi security databases

    wolfi-dev/secdb’s past year of commit activity
    Go 8 Apache-2.0 6 0 1 Updated Jan 6, 2024