containerd

containerd is an industry-standard container runtime that manages the complete container lifecycle on a single host: image pull and storage, container execution, low-level filesystem snapshots, mounts, and event streaming. It runs as a daemon on Linux and Windows and is designed to be embedded into larger systems such as Docker and Kubernetes rather than used directly by end users.

This wiki is a code-level guide to the containerd/containerd repository — how the daemon is structured, what its plugins do, how its services and APIs fit together, and where to start when modifying it.

What this repository ships

• containerd — the daemon that exposes gRPC/ttrpc services and orchestrates plugins. Source: cmd/containerd/.
• containerd-shim-runc-v2 — the per-container shim that talks to runc and reports task lifecycle events back to the daemon. Source: cmd/containerd-shim-runc-v2/.
• ctr — a development/debug CLI for poking the daemon. Source: cmd/ctr/.
• containerd-stress — a load test driver. Source: cmd/containerd-stress/.
• The Go client library at client/ for embedding containerd as a programmatic interface.
• The CRI plugin in internal/cri/ implementing the Kubernetes Container Runtime Interface.
• A protobuf API package in api/ (vendored under its own go.mod).

Reading order

1. Architecture — the daemon, plugin model, shims, and the request flow.
2. Getting started — build, install, run, smoke-test.
3. Glossary — vocabulary used throughout the codebase.
4. How to contribute — workflow, tests, conventions.
5. The lens sections that follow:
   • Apps: the binaries
   • Systems: the in-process subsystems
   • Plugins: pluggable extension points
   • Packages: reusable libraries under pkg/ and client/
   • API: protobuf services
   • Reference: config, dependencies
   • Background: design intent, history, scope

Project status

containerd is a CNCF graduated project. The repository is on its v2 line (go.mod declares module github.com/containerd/containerd/v2). Branch: main. Latest tag at the time of this wiki: v2.3.0 preparation merge (2976f38c, Apr 2026).

Where the code is

Top-level directory	Purpose
api/	Protobuf service and event definitions; published as a separate Go module
client/	Embeddable Go client for containerd (formerly the containerd package in v1)
cmd/	main packages: daemon, shim, ctr, stress, gen-manpages
core/	Core interface definitions and built-in implementations (runtime, content, images, snapshots, sandbox, transfer, …)
defaults/	Compile-time default paths and addresses
docs/	Project documentation in Markdown
internal/	Non-public packages used by the daemon (CRI server, fsverity, NRI helpers, …)
pkg/	Public/non-core helpers (oci, archive, dialer, namespaces, sys, …)
plugins/	Built-in plugins registered via init() (snapshotters, services, server transports)
vendor/	Vendored Go modules

containerd places source files in the directories listed above and disallows new code in the repository root since v2.0 (see CONTRIBUTING.md).