# kuasar-io/kuasar architecture

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

- Interactive diagram: https://gitdiagram.com/kuasar-io/kuasar
- Repository: https://github.com/kuasar-io/kuasar

## Overview

##### Project Type and Purpose
- Kuasar is an open-source, Rust-based container runtime built on top of containerd’s new Sandbox API.
- It serves as a “sandboxer” platform, offering multiple isolation techniques (MicroVM, App Kernel/Quark, Wasm, runC) as external plugins to containerd.
- Its goal is to unify sandbox management, improve startup performance (1:N model), and support pluggable sandboxes.

##### High-Level Architecture Components
A. Control Plane
- containerd (with CRI plugin)
- kuasar-shim (for compatibility with containerd v1.7)
B. Plugin Plane (all separate Unix-socket–based processes)
- vmm-sandboxer
- quark-sandboxer
- wasm-sandboxer
- runc-sandboxer
C. Task Plane (inside or alongside the sandbox)
- vmm-task (runs inside a VM via vsock/UDS)
- quark-task (inside QVisor + QKernel)
- wasm-task (forks WasmEdge/Wasmtime runtime)
- runc-task (joins host namespace)
D. Runtime Plane
- VMM backends: Cloud Hypervisor, StratoVirt, QEMU (inside VM)
- App kernel: QVisor + QKernel
- Wasm runtimes: WasmEdge, Wasmtime
- runC binary
E. Supporting Modules & Tools
- shim code (in /shim) for request forwarding
- scripts and Makefile to build containerd, VMM images, kernels
- docs, examples, benchmarks

##### Interactions and Data Flows
1. containerd (or Kubernetes via CRI) issues a sandbox-create or task-start request.
2. Request goes through kuasar-shim (if using containerd 1.7) to the sandboxer’s Unix socket.
3. Sandboxer’s RPC server implements the Sandbox API (CreateSandbox/DeleteSandbox) and the Task API (CreateTask/Start/Exec/IO/Stop).
4. The sandboxer either:
- Launches a VM (vmm-sandboxer → VM via QEMU/Cloud Hypervisor/StratoVirt) and communicates with vmm-task over vsock/UDS.
- Starts QVisor + QKernel for Quark, and uses quark-task inside QVisor to manage containers.
- Forks a Wasm runtime process (wasm-task) to host Wasm code.
- Double-forks and sets up namespaces for runc-task.
5. IO streams (stdin/stdout/stderr) and control signals flow over Unix domain sockets or vsock.
6. Tasks run container processes/pods; metrics and logs can be stored or forwarded (e.g., via vmm/common/tracing).

##### Architectural Patterns & Design Principles
- Plugin-based microservices: each sandboxer is a standalone process exposing a well-defined gRPC/TTRPC interface over a Unix socket.
- 1:N process model: a single resident sandboxer process manages multiple container tasks, reducing overhead.
- Facade/Adapter: unified Sandbox API façade abstracts over heterogeneous runtimes (VM, Wasm, App Kernel, runc).
- Modular crates: each sandboxer (quark, runc, shim, wasm, vmm/common, vmm/sandbox, vmm/task) is an independent Rust crate.
- Configuration by TOML, scripting for build and image preparation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Plane
    subgraph "Control Plane"
        direction TB
        K8s["Kubernetes/CRI"]:::blue
        Containerd["containerd (CRI plugin)"]:::blue
        Shim["kuasar-shim"]:::blue
    end

    %% Plugin Plane
    subgraph "Plugin Plane"
        direction TB
        VMM_SB["vmm-sandboxer\n(/vmm/sandbox)"]:::green
        VMM_SB --> SB_API1["Sandbox API Server"]:::green
        VMM_SB --> TASK_API1["Task API Server"]:::green

        Quark_SB["quark-sandboxer\n(/quark)"]:::green
        Quark_SB --> SB_API2["Sandbox API Server"]:::green
        Quark_SB --> TASK_API2["Task API Server"]:::green

        Wasm_SB["wasm-sandboxer\n(/wasm)"]:::green
        Wasm_SB --> SB_API3["Sandbox API Server"]:::green
        Wasm_SB --> TASK_API3["Task API Server"]:::green

        Runc_SB["runc-sandboxer\n(/runc)"]:::green
        Runc_SB --> SB_API4["Sandbox API Server"]:::green
        Runc_SB --> TASK_API4["Task API Server"]:::green
    end

    %% Runtime & Task Plane
    subgraph "Runtime & Task Plane"
        direction TB
        VMM_SB -->|"Launch VM"| VM["VM\n(Cloud-Hypervisor, StratoVirt, QEMU)"]:::yellow
        VM -->|"vsock/UDS"| VMM_TASK["vmm-task\n(/vmm/task)"]:::orange

        Quark_SB -->|"Start QVisor+QKernel"| AK["App Kernel\n(QVisor+QKernel)"]:::yellow
        AK -->|"uds"| QUARK_TASK["quark-task\n(quark/src/utils.rs)"]:::orange

        Wasm_SB -->|"Fork runtime"| WR["Wasm Runtime\n(WasmEdge, Wasmtime)"]:::yellow
        WR -->|"uds"| WASM_TASK["wasm-task\n(/wasm)"]:::orange

        Runc_SB -->|"Setup namespaces"| NS["Host Namespace\n(PID Namespace)"]:::yellow
        NS -->|"uds"| RUNC_TASK["runc-task\n(runc/src/task.rs)"]:::orange
    end

    %% Interactions
    K8s -->|"CRI calls"| Containerd
    Containerd -->|"sandbox-create / task-start"| Shim
    Shim -->|"via UDS"| VMM_SB
    Shim -->|"via UDS"| Quark_SB
    Shim -->|"via UDS"| Wasm_SB
    Shim -->|"via UDS"| Runc_SB

    %% Supporting Modules & Tools
    subgraph "Support Modules & Tools"
        direction TB
        Common["Shared Protos & API\n(/vmm/common)"]:::blue
        Build["Build Scripts & Makefile"]:::blue
        Docs["Docs & Examples"]:::blue
    end

    %% Click Events
    click Shim "https://github.com/kuasar-io/kuasar/tree/main/shim/"
    click Shim "https://github.com/kuasar-io/kuasar/blob/main/shim/src/bin/containerd-shim-kuasar-vmm-v2.rs"
    click Shim "https://github.com/kuasar-io/kuasar/blob/main/shim/src/bin/containerd-shim-kuasar-wasm-v2.rs"
    click Shim "https://github.com/kuasar-io/kuasar/blob/main/shim/src/service.rs"

    click VMM_SB "https://github.com/kuasar-io/kuasar/tree/main/vmm/sandbox/"
    click VMM_SB "https://github.com/kuasar-io/kuasar/blob/main/vmm/sandbox/src/bin/cloud_hypervisor/main.rs"
    click VMM_SB "https://github.com/kuasar-io/kuasar/blob/main/vmm/sandbox/src/bin/qemu/main.rs"
    click VMM_SB "https://github.com/kuasar-io/kuasar/blob/main/vmm/sandbox/src/bin/stratovirt/main.rs"
    click SB_API1 "https://github.com/kuasar-io/kuasar/blob/main/vmm/sandbox/src/sandbox.rs"

    click Quark_SB "https://github.com/kuasar-io/kuasar/tree/main/quark/"
    click Quark_SB "https://github.com/kuasar-io/kuasar/blob/main/quark/src/main.rs"
    click SB_API2 "https://github.com/kuasar-io/kuasar/blob/main/quark/src/sandbox.rs"
    click TASK_API2 "https://github.com/kuasar-io/kuasar/blob/main/quark/src/utils.rs"

    click Wasm_SB "https://github.com/kuasar-io/kuasar/tree/main/wasm/"
    click Wasm_SB "https://github.com/kuasar-io/kuasar/blob/main/wasm/src/main.rs"
    click SB_API3 "https://github.com/kuasar-io/kuasar/blob/main/wasm/src/sandbox.rs"
    click WASM_TASK "https://github.com/kuasar-io/kuasar/blob/main/wasm/src/wasmedge.rs"
    click WASM_TASK "https://github.com/kuasar-io/kuasar/blob/main/wasm/src/wasmtime.rs"

    click Runc_SB "https://github.com/kuasar-io/kuasar/tree/main/runc/"
    click Runc_SB "https://github.com/kuasar-io/kuasar/blob/main/runc/src/main.rs"
    click SB_API4 "https://github.com/kuasar-io/kuasar/blob/main/runc/src/sandbox.rs"
    click RUNC_TASK "https://github.com/kuasar-io/kuasar/blob/main/runc/src/task.rs"

    click VMM_TASK "https://github.com/kuasar-io/kuasar/tree/main/vmm/task/"
    click VMM_TASK "https://github.com/kuasar-io/kuasar/blob/main/vmm/task/src/main.rs"
    click VMM_TASK "https://github.com/kuasar-io/kuasar/blob/main/vmm/task/src/task.rs"
    click VMM_TASK "https://github.com/kuasar-io/kuasar/blob/main/vmm/task/src/sandbox_service.rs"

    click Common "https://github.com/kuasar-io/kuasar/tree/main/vmm/common/"
    click Common "https://github.com/kuasar-io/kuasar/tree/main/vmm/common/src/api/"
    click Common "https://github.com/kuasar-io/kuasar/tree/main/vmm/common/src/protos/"

    click Build "https://github.com/kuasar-io/kuasar/tree/main/Makefile"
    click Build "https://github.com/kuasar-io/kuasar/tree/main/scripts/"
    click Build "https://github.com/kuasar-io/kuasar/tree/main/vmm/scripts/"

    click Docs "https://github.com/kuasar-io/kuasar/tree/main/docs/"
    click Docs "https://github.com/kuasar-io/kuasar/tree/main/examples/"

    %% Styles
    classDef blue fill:#D6E4F0,stroke:#4A90E2,color:#000
    classDef green fill:#DFF2D8,stroke:#3C763D,color:#000
    classDef yellow fill:#FEF3C7,stroke:#F1C40F,color:#000
    classDef orange fill:#FDE2D1,stroke:#D35400,color:#000
```
