# opencontainers/runc architecture

> Architecture diagram of the GitHub repository opencontainers/runc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opencontainers/runc
- Repository: https://github.com/opencontainers/runc

## Overview

runc is a Linux OCI container runtime, commonly invoked by higher-level container software. Its main workflow takes a container bundle and lifecycle command, converts the OCI specification into runtime configuration, then creates and starts a container with namespaces, a prepared root filesystem, resource controls, and security settings. The README establishes the product and bundle workflow; sampled source and the SOURCE INDEX support several internal relationships. Many command-handler and lifecycle details are unsampled, so those links are marked unverified rather than treated as inspected call paths.

Main entry points: [`libcontainer/container_linux.go`](https://github.com/opencontainers/runc/blob/main/libcontainer/container_linux.go) (Container lifecycle), [`libcontainer/process_linux.go`](https://github.com/opencontainers/runc/blob/main/libcontainer/process_linux.go) (Process launch), [`libcontainer/configs/config.go`](https://github.com/opencontainers/runc/blob/main/libcontainer/configs/config.go) (Runtime config), [`main.go`](https://github.com/opencontainers/runc/blob/main/main.go) (runc CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and OCI"]
  node_cli["runc CLI<br/>[main.go]"]
  node_bundle["OCI bundle"]
  node_conversion["Spec conversion<br/>[spec_linux.go]"]
  node_validation["Config validation<br/>[validator.go]"]
  node_config["Runtime config<br/>[config.go]"]
end

subgraph group_runtime["Container lifecycle"]
  node_container["Container lifecycle<br/>[container_linux.go]"]
  node_process["Process launch<br/>[process_linux.go]"]
  node_checkpoint["Checkpoint and restore<br/>[criu_linux.go]"]
end

subgraph group_isolation["Isolation and security"]
  node_nsbootstrap["Namespace bootstrap<br/>[nsexec.c]"]
  node_rootfs["Root filesystem<br/>[rootfs_linux.go]"]
  node_capabilities["Capabilities<br/>[capabilities.go]"]
  node_apparmor["AppArmor<br/>[apparmor_linux.go]"]
  node_seccomp["Seccomp filters<br/>[seccomp_linux.go]"]
end

subgraph group_management["Resource management"]
  node_cgroups["Cgroup controls<br/>[process_linux.go]"]
  node_network["Container networking<br/>[process_linux.go]"]
  node_intelrdt["Intel RDT<br/>[intelrdt.go]"]
  node_stats["Runtime statistics<br/>[stats_linux.go]"]
end

node_operator(("Runtime caller"))

node_operator -->|"invokes"| node_cli
node_bundle -.->|"supplies config"| node_cli
node_cli -.->|"converts spec"| node_conversion
node_conversion -->|"builds config"| node_config
node_validation -->|"validates"| node_config
node_container -.->|"starts process"| node_process
node_process -->|"uses settings"| node_config
node_process -->|"adds process"| node_cgroups
node_process -->|"sets up"| node_network
node_process -->|"manages"| node_intelrdt
node_container -.->|"prepares rootfs"| node_rootfs
node_rootfs -->|"reads mounts"| node_config
node_process -.->|"launches via"| node_nsbootstrap
node_container -.->|"applies"| node_capabilities
node_container -.->|"configures"| node_apparmor
node_container -.->|"configures"| node_seccomp
node_container -.->|"checkpoints"| node_checkpoint
node_container -.->|"reports stats"| node_stats

click node_cli "https://github.com/opencontainers/runc/blob/main/main.go"
click node_conversion "https://github.com/opencontainers/runc/blob/main/libcontainer/specconv/spec_linux.go"
click node_validation "https://github.com/opencontainers/runc/blob/main/libcontainer/configs/validate/validator.go"
click node_config "https://github.com/opencontainers/runc/blob/main/libcontainer/configs/config.go"
click node_container "https://github.com/opencontainers/runc/blob/main/libcontainer/container_linux.go"
click node_process "https://github.com/opencontainers/runc/blob/main/libcontainer/process_linux.go"
click node_nsbootstrap "https://github.com/opencontainers/runc/blob/main/libcontainer/nsenter/nsexec.c"
click node_rootfs "https://github.com/opencontainers/runc/blob/main/libcontainer/rootfs_linux.go"
click node_capabilities "https://github.com/opencontainers/runc/blob/main/libcontainer/capabilities/capabilities.go"
click node_apparmor "https://github.com/opencontainers/runc/blob/main/libcontainer/apparmor/apparmor_linux.go"
click node_seccomp "https://github.com/opencontainers/runc/blob/main/libcontainer/seccomp/seccomp_linux.go"
click node_cgroups "https://github.com/opencontainers/runc/blob/main/libcontainer/process_linux.go"
click node_network "https://github.com/opencontainers/runc/blob/main/libcontainer/process_linux.go"
click node_intelrdt "https://github.com/opencontainers/runc/blob/main/libcontainer/intelrdt/intelrdt.go"
click node_stats "https://github.com/opencontainers/runc/blob/main/libcontainer/stats_linux.go"
click node_checkpoint "https://github.com/opencontainers/runc/blob/main/libcontainer/criu_linux.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_bundle,node_conversion,node_validation,node_config toneBlue
class node_container,node_process,node_checkpoint toneAmber
class node_nsbootstrap,node_rootfs,node_capabilities,node_apparmor,node_seccomp toneMint
class node_cgroups,node_network,node_intelrdt,node_stats toneRose
class node_operator toneIndigo
```

## Components

### CLI and OCI

- [runc CLI](https://github.com/opencontainers/runc/blob/main/main.go): `main.go`
- **OCI bundle**
- [Spec conversion](https://github.com/opencontainers/runc/blob/main/libcontainer/specconv/spec_linux.go): `libcontainer/specconv/spec_linux.go`
- [Config validation](https://github.com/opencontainers/runc/blob/main/libcontainer/configs/validate/validator.go): `libcontainer/configs/validate/validator.go`
- [Runtime config](https://github.com/opencontainers/runc/blob/main/libcontainer/configs/config.go): `libcontainer/configs/config.go`

### Container lifecycle

- [Container lifecycle](https://github.com/opencontainers/runc/blob/main/libcontainer/container_linux.go): `libcontainer/container_linux.go`
- [Process launch](https://github.com/opencontainers/runc/blob/main/libcontainer/process_linux.go): `libcontainer/process_linux.go`
- [Checkpoint and restore](https://github.com/opencontainers/runc/blob/main/libcontainer/criu_linux.go): `libcontainer/criu_linux.go`

### Isolation and security

- [Namespace bootstrap](https://github.com/opencontainers/runc/blob/main/libcontainer/nsenter/nsexec.c): `libcontainer/nsenter/nsexec.c`
- [Root filesystem](https://github.com/opencontainers/runc/blob/main/libcontainer/rootfs_linux.go): `libcontainer/rootfs_linux.go`
- [Capabilities](https://github.com/opencontainers/runc/blob/main/libcontainer/capabilities/capabilities.go): `libcontainer/capabilities/capabilities.go`
- [AppArmor](https://github.com/opencontainers/runc/blob/main/libcontainer/apparmor/apparmor_linux.go): `libcontainer/apparmor/apparmor_linux.go`
- [Seccomp filters](https://github.com/opencontainers/runc/blob/main/libcontainer/seccomp/seccomp_linux.go): `libcontainer/seccomp/seccomp_linux.go`

### Resource management

- [Cgroup controls](https://github.com/opencontainers/runc/blob/main/libcontainer/process_linux.go): `libcontainer/process_linux.go`
- [Container networking](https://github.com/opencontainers/runc/blob/main/libcontainer/process_linux.go): `libcontainer/process_linux.go`
- [Intel RDT](https://github.com/opencontainers/runc/blob/main/libcontainer/intelrdt/intelrdt.go): `libcontainer/intelrdt/intelrdt.go`
- [Runtime statistics](https://github.com/opencontainers/runc/blob/main/libcontainer/stats_linux.go): `libcontainer/stats_linux.go`

### Other components

- **Runtime caller**

## Connections

- Runtime caller → runc CLI: invokes
- OCI bundle → runc CLI: supplies config
- runc CLI → Spec conversion: converts spec
- Spec conversion → Runtime config: builds config (evidence: `libcontainer/specconv/spec_linux.go`)
- Config validation → Runtime config: validates (evidence: `libcontainer/configs/validate/validator.go`)
- Container lifecycle → Process launch: starts process
- Process launch → Runtime config: uses settings (evidence: `libcontainer/process_linux.go`)
- Process launch → Cgroup controls: adds process (evidence: `libcontainer/process_linux.go`)
- Process launch → Container networking: sets up (evidence: `libcontainer/process_linux.go`)
- Process launch → Intel RDT: manages (evidence: `libcontainer/process_linux.go`)
- Container lifecycle → Root filesystem: prepares rootfs
- Root filesystem → Runtime config: reads mounts (evidence: `libcontainer/rootfs_linux.go`)
- Process launch → Namespace bootstrap: launches via
- Container lifecycle → Capabilities: applies
- Container lifecycle → AppArmor: configures
- Container lifecycle → Seccomp filters: configures
- Container lifecycle → Checkpoint and restore: checkpoints
- Container lifecycle → Runtime statistics: reports stats
