# containers/crun architecture

> Architecture diagram of the GitHub repository containers/crun, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/containers/crun
- Repository: https://github.com/containers/crun

## Overview

##### Main Components
- CLI & Orchestration Layer: Files like src/crun.c, src/create.c, src/start.c, src/exec.c, etc., form the command-line interface and process control layer for container operations.
- Core Container Runtime Library (libcrun): The most significant part is found under src/libcrun. This submodule includes modules for container lifecycle management, cgroup support, seccomp filtering, signal handling, mount management, and even specialized handlers for various container backends (like Mono, WASM runtimes, etc. in handlers/).
- OS Integration & System Interfaces: There is heavy interaction with Linux kernel features such as cgroups (files like cgroup-cgroupfs.c, cgroup-systemd.c, and related utilities), seccomp (seccomp.c, seccomp_notify.c), and namespace handling. This represents the interface that crun uses to create, monitor, and clean-up container processes.
- Build and Configuration Infrastructure: Scripts like autogen.sh, configure.ac, Makefile.am, cfg.mk, and directories like build-aux and m4 denote a conventional GNU autotools build system – highlighting configurable and modular build aspects.
- Contributed Plugins and Examples: Look at the contrib/ directory (e.g., seccomp-notify-plugin-example, terminal-receiver, etc.) which offer extensibility points and integration examples for notification and seccomp handling.
- Bindings / Language Integrations: The lua/ directory (including lua_crun.c and related rockspec files) shows that there is a Lua binding available, while the python/ directory supports Python integrations (evidenced by crun_python.c).
- Tests & Validation: The tests/ directory includes various Dockerfiles, shell scripts, and unit tests (including tests for capabilities, seccomp, mounts, etc.) to ensure system compliance with OCI specs and robust functionality.

##### Relationships and Interactions
- The CLI layer interacts with the core libcrun library to perform operations such as container creation, delete, exec, and update. These operations are all defined in corresponding source files (e.g., create.c, exec.c, etc.).
- libcrun then interacts directly with the Linux kernel interfaces (via cgroups, seccomp, namespaces, etc.) to enforce isolation, resource limits, and security policies.
- The plugin handlers (e.g., from handlers/ directory) allow for integration with additional functionalities like support for various container runtimes or extensions for languages (e.g., WASM runtimes).
- The build configuration and scripts manage how the overall project pieces are combined, enabling static and shared builds, and even integration with reproducible package systems like Nix.
- The tests simulate different runtime scenarios, ensuring that each component (from CLI processing to OS API interactions) meets the defined OCI specifications.

##### Architectural Patterns & Design Principles
- Modularization: There is a clear separation between the command interface and the core runtime library.
- Layered Design: Higher-level commands (CLI layer) call into lower-level, specialized modules (libcrun) that directly communicate with the OS.
- Extensibility: The presence of a plugins directory and bindings for multiple programming languages indicates an architectural intention to allow for future enhancements or integrations.
- Isolation and Abstraction: The runtime cleanly abstracts away complex interactions with kernel level features (cgroups, seccomp) from the user-facing operations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Orchestration Layer
    subgraph "CLI & Orchestration Layer"
        cli_crun["crun.c"]:::cli
        cli_create["create.c"]:::cli
        cli_exec["exec.c"]:::cli
        cli_delete["delete.c"]:::cli
        cli_kill["kill.c"]:::cli
        cli_start["start.c"]:::cli
        cli_run["run.c"]:::cli
    end

    %% Core Container Runtime Library (libcrun)
    subgraph "Core Container Runtime Library (libcrun)"
        lib_container["Container Lifecycle Management"]:::lib
        lib_seccomp["Seccomp Filtering Module"]:::lib
        lib_cgroup["Cgroup Management Module"]:::lib
        lib_mount["Mount Management Module"]:::lib
        lib_handlers["Specialized Handlers (e.g., Mono, WASM)"]:::lib
    end

    %% OS Integration & System Interfaces
    subgraph "OS Integration & System Interfaces"
        os_cgroupfs["Cgroup (cgroup-cgroupfs.c)"]:::os
        os_systemd["Cgroup (cgroup-systemd.c)"]:::os
        os_seccomp["Seccomp (seccomp.c)"]:::os
        os_seccomp_notify["Seccomp Notify (seccomp_notify.c)"]:::os
        os_mount["Mount Flags (mount_flags.c)"]:::os
        os_linux["Linux Interface (linux.c)"]:::os
    end

    %% Build and Configuration Infrastructure
    subgraph "Build and Configuration Infrastructure"
        build_autogen["autogen.sh"]:::build
        build_configure["configure.ac"]:::build
        build_makefile["Makefile.am"]:::build
        build_cfg["cfg.mk"]:::build
        build_aux["build-aux Directory"]:::build
    end

    %% Contributed Plugins and Examples
    subgraph "Contributed Plugins and Examples"
        plugin_seccomp["Seccomp Notify Plugin Example"]:::plugin
        plugin_terminal["Terminal Receiver"]:::plugin
        plugin_notify["Notify Socket Server"]:::plugin
    end

    %% Bindings / Language Integrations
    subgraph "Bindings / Language Integrations"
        binding_lua["Lua Bindings"]:::bind
        binding_python["Python Integrations"]:::bind
    end

    %% Tests & Validation
    subgraph "Tests & Validation"
        test_suite["Test Suite & OCI Validation"]:::test
    end

    %% Relationships
    %% CLI Layer calls into Core Runtime
    cli_crun -->|"invokes"| lib_container
    cli_create -->|"invokes"| lib_container
    cli_exec -->|"invokes"| lib_container
    cli_delete -->|"invokes"| lib_container
    cli_kill -->|"invokes"| lib_container
    cli_start -->|"invokes"| lib_container
    cli_run -->|"invokes"| lib_container

    %% Core Runtime interactions with OS Interfaces
    lib_container -->|"uses"| os_linux
    lib_seccomp -->|"triggers"| os_seccomp
    lib_seccomp -->|"triggers"| os_seccomp_notify
    lib_cgroup -->|"manages"| os_cgroupfs
    lib_cgroup -->|"manages"| os_systemd
    lib_mount -->|"configures"| os_mount

    %% Specialized Handlers can extend functionality via plugins
    lib_handlers -->|"extends"| plugin_seccomp
    lib_handlers -->|"extends"| plugin_terminal
    lib_handlers -->|"extends"| plugin_notify

    %% Bindings integrate with Core Runtime Library
    binding_lua -->|"binds to"| lib_container
    binding_python -->|"binds to"| lib_container

    %% Build and Configuration builds both CLI and libcrun modules
    build_autogen ---|"builds"| cli_crun
    build_configure ---|"builds"| lib_container
    build_makefile ---|"builds"| cli_exec
    build_cfg ---|"builds"| lib_cgroup
    build_aux ---|"builds"| lib_mount

    %% Tests simulate and validate through CLI and Core Runtime
    test_suite -->|"tests"| cli_crun
    test_suite -->|"tests"| lib_container

    %% Click Events for CLI & Orchestration Layer
    click cli_crun "https://github.com/containers/crun/blob/main/src/crun.c"
    click cli_create "https://github.com/containers/crun/blob/main/src/create.c"
    click cli_exec "https://github.com/containers/crun/blob/main/src/exec.c"
    click cli_delete "https://github.com/containers/crun/blob/main/src/delete.c"
    click cli_kill "https://github.com/containers/crun/blob/main/src/kill.c"
    click cli_start "https://github.com/containers/crun/blob/main/src/start.c"
    click cli_run "https://github.com/containers/crun/blob/main/src/run.c"

    %% Click Event for Core Container Runtime Library
    click lib_container "https://github.com/containers/crun/tree/main/src/libcrun"

    %% Click Events for OS Integration & System Interfaces
    click os_cgroupfs "https://github.com/containers/crun/blob/main/src/libcrun/cgroup-cgroupfs.c"
    click os_systemd "https://github.com/containers/crun/blob/main/src/libcrun/cgroup-systemd.c"
    click os_seccomp "https://github.com/containers/crun/blob/main/src/libcrun/seccomp.c"
    click os_seccomp_notify "https://github.com/containers/crun/blob/main/src/libcrun/seccomp_notify.c"
    click os_mount "https://github.com/containers/crun/blob/main/src/libcrun/mount_flags.c"
    click os_linux "https://github.com/containers/crun/blob/main/src/libcrun/linux.c"

    %% Click Events for Build and Configuration Infrastructure
    click build_autogen "https://github.com/containers/crun/blob/main/autogen.sh"
    click build_configure "https://github.com/containers/crun/blob/main/configure.ac"
    click build_makefile "https://github.com/containers/crun/blob/main/Makefile.am"
    click build_cfg "https://github.com/containers/crun/blob/main/cfg.mk"
    click build_aux "https://github.com/containers/crun/tree/main/build-aux"

    %% Click Events for Contributed Plugins and Examples
    click plugin_seccomp "https://github.com/containers/crun/tree/main/contrib/seccomp-notify-plugin-example"
    click plugin_terminal "https://github.com/containers/crun/tree/main/contrib/terminal-receiver"
    click plugin_notify "https://github.com/containers/crun/tree/main/contrib/notify-socket-server"

    %% Click Events for Bindings / Language Integrations
    click binding_lua "https://github.com/containers/crun/blob/main/lua/lua_crun.c"
    click binding_python "https://github.com/containers/crun/blob/main/python/crun_python.c"

    %% Click Event for Tests & Validation
    click test_suite "https://github.com/containers/crun/tree/main/tests"

    %% Styles
    classDef cli fill:#ccf,stroke:#0000ff,stroke-width:2px;
    classDef lib fill:#cfc,stroke:#008000,stroke-width:2px;
    classDef os fill:#eee,stroke:#666666,stroke-width:2px;
    classDef build fill:#fdd,stroke:#d00,stroke-width:2px;
    classDef plugin fill:#ffd,stroke:#aa0,stroke-width:2px;
    classDef bind fill:#ddf,stroke:#00f,stroke-width:2px;
    classDef test fill:#fdf,stroke:#d0a,stroke-width:2px;
```
