# LinuxKit — Toolkit for Building Secure Container-Optimized OS Images

> Build minimal, immutable Linux distributions purpose-built for running containers. Compose your OS from signed components and produce bootable images for bare metal, VMs, or cloud platforms.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# LinuxKit — Toolkit for Building Secure Container-Optimized OS Images

## Quick Use
```bash
git clone https://github.com/linuxkit/linuxkit.git && cd linuxkit
make && make install
linuxkit build linuxkit.yml
linuxkit run linuxkit
```

## Introduction
LinuxKit is a framework for building secure, minimal, and immutable Linux distributions where every system service runs as a container. Created by Docker Inc., it enables platform teams to compose custom operating systems from individual OCI images and produce bootable artifacts for any environment.

## What LinuxKit Does
- Assembles a custom Linux OS from a YAML manifest listing kernel, init, and service containers
- Produces bootable images for ISO, raw disk, AWS AMI, GCP, Azure, and VMware formats
- Enforces immutability with a read-only root filesystem and tmpfs for runtime state
- Signs and verifies every component using content-addressable OCI image references
- Provides a minimal attack surface with no package manager or shell in production images

## Architecture Overview
A LinuxKit build reads a YAML file specifying a kernel image, an init process (containerd), and system/service containers. The linuxkit tool pulls each OCI image, layers them into a root filesystem, attaches the kernel, and outputs a bootable artifact. At runtime, containerd launches each service as an isolated container with its own namespace and cgroup constraints.

## Self-Hosting & Configuration
- Install the linuxkit CLI from source or grab a release binary for Linux or macOS
- Define your OS in a YAML file listing kernel version, init containers, and services
- Build output formats include iso-bios, iso-efi, raw, qcow2, vhd, and cloud-specific images
- Use content trust by referencing images with their sha256 digest
- Extend with custom packages by publishing OCI images to any container registry

## Key Features
- Everything-is-a-container philosophy reduces OS complexity to a handful of images
- Immutable root filesystem eliminates configuration drift
- Sub-100MB images boot in seconds on bare metal or VMs
- Platform-agnostic output supports local hypervisors, cloud providers, and edge hardware
- Component-level updates replace entire container images rather than patching in place

## Comparison with Similar Tools
- **Bottlerocket (AWS)** — similar immutable OS but AWS-focused; LinuxKit is vendor-neutral
- **Flatcar Container Linux** — pre-built distro; LinuxKit lets you compose your own from scratch
- **Talos Linux** — API-managed K8s OS; LinuxKit is lower-level and more customizable
- **NixOS** — reproducible but heavier; LinuxKit targets minimal container hosts
- **RancherOS** — end-of-life; LinuxKit remains actively maintained

## FAQ
**Q: Is LinuxKit suitable for production Kubernetes nodes?**
A: Yes. Teams use LinuxKit to build minimal node images running containerd and kubelet with nothing else, reducing the attack surface dramatically.

**Q: Can I add debugging tools for development?**
A: Add an optional service container with shell and diagnostic tools in your YAML, then omit it for production builds.

**Q: How do updates work without a package manager?**
A: You rebuild the image with updated component references and re-deploy. The immutable design ensures every node runs an identical, tested configuration.

**Q: What hypervisors can I run LinuxKit images on locally?**
A: The CLI supports HyperKit (macOS), Hyper-V (Windows), and QEMU/KVM (Linux) out of the box.

## Sources
- https://github.com/linuxkit/linuxkit
- https://github.com/linuxkit/linuxkit/blob/master/docs/README.md

---
Source: https://tokrepo.com/en/workflows/linuxkit-toolkit-building-secure-container-optimized-os-cda583fa
Author: AI Open Source