Strip away every layer of tooling built on top of it, and a “container” is just a regular Linux process wearing very specific restrictions.

runc is a small, low-level command-line tool that creates and runs containers according to the OCI Runtime Specification — a written standard, agreed upon by the container industry, that precisely defines what a “container” must look like on disk and how a runtime must behave when asked to start one. runc is the original, reference implementation of that specification, meaning it is the tool the specification itself was largely modeled after and validated against. In plain terms: runc takes a folder containing a root filesystem and a configuration file, and turns that folder into a genuinely running, isolated process on the host machine.

The crucial thing to understand is that runc does not implement any new isolation technology of its own. Linux has offered process isolation primitives for years — namespaces to give a process its own private view of the system, and control groups (cgroups) to limit how much CPU, memory, and I/O a process can consume. runc’s entire job is to correctly and carefully wire these existing kernel features together, in the right order, with the right configuration, every single time — something that is far more fiddly and error-prone to do by hand than it sounds.

runc was not invented in a vacuum — it was extracted from a real, urgent industry problem: fragmentation.

In Docker’s early years, all of the low-level logic for creating namespaces, applying cgroup limits, and starting an isolated process lived inside Docker’s own codebase, in a component called libcontainer. This worked, but it meant that “how a container actually gets created” was defined entirely by one company’s internal implementation. Other projects experimenting with containers — including early competitors and cloud providers — had no shared, agreed-upon definition of what a container even was at the filesystem and process level. Every tool risked reinventing its own slightly different, incompatible version of the same idea.

This history matters because it explains runc’s entire design philosophy. It is deliberately small, deliberately unopinionated, and deliberately does exactly one job — create and run one container, once, per invocation — leaving every higher-level concern (image pulling, networking setup, scheduling, logging) to the layers built on top of it. That narrow focus is precisely what let an entire ecosystem of different, competing tools all confidently build on the same trustworthy foundation.

runc’s entire world revolves around one folder, one file inside it, and a handful of Linux kernel primitives.

graph TB
    subgraph HighLevel["Higher-Level Tooling"]
        DOCKER["Docker Engine"]
        CONTAINERD["containerd"]
        SHIM["containerd-shim"]
    end
    subgraph Bundle["OCI Bundle (prepared on disk)"]
        RFS["Root Filesystem (unpacked image layers)"]
        CFG["config.json (OCI runtime spec)"]
    end
    RUNC["runc (OCI runtime)"]
    subgraph Kernel["Linux Kernel Primitives"]
        NS["Namespaces"]
        CG["cgroups"]
        CAP["Capabilities / seccomp"]
    end
    PROC["Isolated Container Process"]

    DOCKER --> CONTAINERD --> SHIM --> RUNC
    RFS --> RUNC
    CFG --> RUNC
    RUNC --> NS --> PROC
    RUNC --> CG --> PROC
    RUNC --> CAP --> PROC
    

This chapter opens the hood on the exact sequence of kernel-level steps runc performs to turn a bundle into an isolated process.

Creating Namespaces

Linux offers several distinct namespace types, and runc creates whichever combination config.json requests, typically all of the following for a standard container: a PID namespace so the container’s processes get their own independent process-ID numbering starting near 1; a network namespace so the container gets its own private network interfaces and routing table; a mount namespace so the container’s view of mounted filesystems is separate from the host’s; a UTS namespace so the container can have its own hostname; and an IPC namespace isolating inter-process communication mechanisms. Each namespace independently hides one category of system state from the container, and together they create the overall illusion of a private machine.

Setting Up the Root Filesystem: pivot_root

Before the container’s actual command runs, runc must change what the process considers to be the root of the filesystem, from the host’s real root directory to the container’s own root filesystem, extracted from its image layers. runc typically uses a system call called pivot_root to perform this swap, which is more secure than the older chroot mechanism because it fully moves the old root out of the new mount namespace rather than merely changing a path prefix, making it substantially harder for a process to “break out” back to the host’s original filesystem.

Applying Control Group Limits

Once namespaces are established, runc creates a dedicated cgroup for the container and writes the resource limits from config.json into it — maximum memory, CPU share or quota, and I/O weight, among others. The kernel then enforces these limits automatically for every process running inside that container, for the entire lifetime of the container, without runc needing to actively police anything after the fact.

Dropping Privileges and Applying Security Restrictions

Before finally executing the container’s command, runc applies the remaining security settings from config.json: dropping unnecessary Linux capabilities (fine-grained privileges that would normally come bundled with running as root), applying a seccomp filter that blocks the process from making dangerous system calls, and setting up mandatory access control profiles if the platform uses SELinux or AppArmor. Only after every one of these steps has succeeded does runc finally call execve to replace itself with the actual container process.

runc’s command-line interface maps directly onto the distinct stages a container passes through, from nothing to running to gone.

sequenceDiagram
    participant Caller as containerd-shim
    participant Runc as runc
    participant Kernel as Linux Kernel
    participant Proc as Container Process

    Caller->>Runc: runc create (bundle path, container id)
    Runc->>Kernel: create namespaces, cgroup, pivot_root
    Kernel-->>Runc: process created, paused before exec
    Runc-->>Caller: container created (not yet running)

    Caller->>Runc: runc start (container id)
    Runc->>Proc: release process to execute its command
    Proc-->>Caller: container now running

    Caller->>Runc: runc kill / runc delete
    Runc->>Kernel: send signal, tear down cgroup and namespaces
    Kernel-->>Runc: process terminated, resources reclaimed
    

The deliberate split between create and start is one of runc’s most important design decisions. It exists because the calling tool — usually a lightweight process called a shim — often needs to finish its own setup work, such as wiring up standard input and output streams or registering the container with a higher-level system, after the isolated environment exists but before user code inside it actually starts running. Combining creation and execution into a single step would remove that safe window entirely.

The way higher-level tools use runc reveals some clear best-practice patterns — and some equally clear mistakes.

Pattern: The Shim-per-Container Model

containerd does not call runc directly and then wait around for the container to finish. Instead, it launches a small, independent long-running process called a shim for each container, and that shim invokes runc to create and start the container. Once the container is running, runc itself exits — the shim, not runc, stays alive to track the container’s process, forward its exit status, and keep standard input and output streams connected. This means a restart of containerd or even the Docker daemon does not kill already-running containers, because those containers’ survival never depended on runc or the higher-level daemon staying alive.

Anti-Pattern: Calling Runc Directly in Production Automation

Because runc is intentionally low-level and unopinionated, it does not handle image pulling, logging, networking configuration, or restart policies on its own. Building custom production tooling that shells out to runc directly, bypassing containerd or a similar daemon, means reimplementing a large amount of battle-tested logic that the ecosystem has already solved — a classic case of an appealing shortcut creating significant hidden long-term maintenance cost.

Anti-Pattern: Assuming Runc Manages Networking

runc creates the network namespace a container lives in, but it does not configure interfaces, IP addresses, or routing inside that namespace by default — that is deliberately left to a separate component (typically a CNI plugin in the Kubernetes world). Teams occasionally assume runc handles networking end to end and are confused when a freshly created container has an isolated but entirely empty network namespace.

runc’s narrow focus is simultaneously its greatest strength and the source of its most common criticisms.

These trade-offs are exactly why the container ecosystem grew a second category of OCI-compliant runtimes — often called sandboxed or “secure” runtimes — that implement stronger isolation, frequently by running each container inside its own lightweight virtual machine, at the cost of somewhat higher overhead per container. runc remains the default for the vast majority of workloads precisely because its speed and simplicity outweigh the isolation gap for most trusted, well-managed environments.

Because runc sits directly on the boundary between a container and the host kernel, its security posture matters enormously.

Shared Kernel, Shared Risk

Every container started by runc shares the exact same host kernel as every other container and the host operating system itself. Namespaces and cgroups restrict what a process can see and use, but they do not create a separate kernel per container the way a virtual machine would. This means a sufficiently severe kernel-level vulnerability, if exploited from inside a container, has the potential to affect the entire host, which is the fundamental isolation ceiling of namespace-based containers regardless of how carefully runc itself is implemented.

Seccomp, Capabilities, and Mandatory Access Control

runc’s default configuration, inherited from the OCI specification’s recommended defaults, drops a long list of Linux capabilities that are rarely needed by ordinary application workloads, and applies a seccomp filter blocking system calls that are common vectors for container escapes or kernel exploitation. Platforms layering SELinux or AppArmor profiles on top add a further, independent restriction, so that even if one security layer is bypassed, others remain in place — the same defense-in-depth principle that governs every well-designed container platform.

The Rise of Sandboxed Alternatives

For workloads that must run genuinely untrusted or multi-tenant code — for example, a platform that lets external customers upload arbitrary code to execute — many organizations choose an OCI-compliant sandboxed runtime instead of runc, giving each container the stronger isolation boundary of a lightweight virtual machine while still fitting into the exact same OCI-based tooling and Kubernetes workflows.

Because runc itself is short-lived per invocation, meaningful monitoring happens at the layers around it, using data runc exposes.

runc does not run a persistent background process, log continuously, or expose a metrics endpoint of its own — it executes a specific command, does its job, and (aside from the container process it created) exits. Observability therefore comes from two places: the runc state command, which higher-level tools poll to check whether a container is created, running, or stopped, and the underlying cgroup filesystem, which the kernel continuously updates with real-time resource usage figures for every container runc set up, without runc needing to actively report anything itself.

Production platforms typically monitor at the containerd or Kubernetes layer rather than watching runc invocations directly, since those higher layers aggregate the per-container cgroup statistics runc’s setup makes available into fleet-wide dashboards covering CPU throttling, memory pressure, and out-of-memory kill events. When something does go wrong specifically inside runc’s own execution — a failed namespace creation, a misconfigured mount, a seccomp filter rejecting an unexpected system call — it typically surfaces as an error returned from the runc create or runc start call itself, which the calling shim then logs and propagates upward.

Most day-to-day engineers never call runc directly, but understanding these practices explains a great deal of container platform behavior.

runc is not a theoretical piece of infrastructure — it is doing real work, right now, under nearly every major container platform in production.

No — Docker is a full platform handling image building, networking, volumes, and the user-facing command-line experience. runc is one small component several layers underneath Docker, specifically responsible for the final step of actually creating and starting the isolated Linux process.

No. The vast majority of engineers never call runc directly; it is invoked automatically by containerd, Docker, or Kubernetes behind the scenes. Understanding it is valuable for debugging and system design, not for everyday container usage.

containerd is a higher-level daemon that manages the full container lifecycle — pulling images, managing storage, handling networking setup, and supervising containers over time. runc is the low-level tool containerd calls, through a per-container shim, to perform the actual namespace and cgroup creation for a single container at a single moment.

Yes. runc only needs a valid OCI bundle — a root filesystem directory and a config.json file — and does not inherently know or care whether that root filesystem originated from a pulled container image, a hand-built directory, or any other source.

Because the OCI Runtime Specification standardizes the interface, Kubernetes can let different workloads select different runtimes — typically runc for speed on trusted workloads, and a sandboxed VM-backed alternative for workloads needing stronger isolation — through Kubernetes’ runtime class mechanism, without changing how pods are otherwise defined or scheduled.

runc creates the network namespace a container lives inside, giving it isolation from the host’s networking, but it does not configure IP addresses, interfaces, or routes within that namespace by default. That configuration is handled separately, typically by a CNI plugin invoked by the higher-level orchestrator.