# microsoft/hcsshim architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/hcsshim
- Repository: https://github.com/microsoft/hcsshim

## Overview

##### Project Type and Purpose
- This is primarily a Go “library + CLI” project providing:
- A Go interface to the Windows Host Compute Service (HCS) and Host Network Service (HNS)
- A Containerd Runtime V2 shim (containerd-shim-runhcs-v1 / runhcs) for Windows containers
- A Linux Hyper-V container guest agent (cmd/gcs) and side-car
- Supporting utilities (wclayer, computestorage, ext4/tar2ext4, ncproxy, shimdiag, etc.)
- It’s consumed by container runtimes (e.g., Moby, containerd) to launch/manage Windows & Linux-in-VM containers.

##### File Structure
- Top-level cmd/… folders: the various CLI binaries
- internal/… packages: host-side libraries for HCS, HNS, UVM, guest bridge, storage, networking, security, logging, etc.
- pkg/…: externally consumable Go packages (e.g., go-runhcs, ncproxy gRPC proxies, securitypolicy)
- ext4/, computestorage/: file-system tooling for Linux containers
- scripts/, Makefile: build/test pipelines
- test/: integration & unit tests

##### README Insights
- Describes two main binaries:
- cmd/containerd-shim-runhcs-v1 (Windows shim for containerd Runtime V2 API)
- cmd/gcs (Linux guest agent)
- Mentions Go interfaces for HCS and HNS, and integration points into containerd and Moby.

##### Detail Level
- Core flows—container lifecycle, network setup, filesystem provisioning, guest signaling
- Avoid diving into every internal package; instead, show representative modules by capability (compute, network, storage, guest bridge)
- Important extension points: pkg/go-runhcs, pkg/ncproxy, pkg/securitypolicy

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Containerd["Containerd"]:::external

    %% Host-side Shim Binaries
    subgraph "Runtime Shim (CLI)" 
        ShimRunhcs1["containerd-shim-runhcs-v1"]:::host
        ShimRunhcs2["runhcs"]:::host
    end

    %% Host Libraries
    subgraph "Host Libraries" 
        HCS["internal/hcs"]:::host
        HNS["internal/hns"]:::host
        UVM["internal/uvm"]:::host
        GCSHostSide["internal/gcs-sidecar"]:::host
    end

    %% Windows OS Services
    subgraph "Windows OS Services" 
        HCSsvc["Host Compute Service (HCS)"]:::os
        HNSsvc["Host Network Service (HNS)"]:::os
        WinAPI["WinAPI / zsyscall"]:::os
    end

    %% Hypervisor & Utility VM
    Hypervisor["Hyper-V Hypervisor"]:::os
    subgraph "Utility VM" 
        VM["Utility VM"]:::vm
        GCSGuest["cmd/gcs"]:::vm
        GuestLib["internal/guest"]:::vm
    end

    %% Storage Tools
    subgraph "Storage Tools" 
        WCLayerCLI["cmd/wclayer"]:::tools
        WCLayerLib["internal/wclayer"]:::tools
        CompStorage["computestorage"]:::storage
        Ext4CLI["cmd/tar2ext4"]:::tools
        Ext4Lib["ext4"]:::storage
    end

    %% Networking Helpers
    subgraph "Networking Helpers"
        HCN["hcn"]:::network
        NCProxyCLI["cmd/ncproxy"]:::tools
        NCProxyLib["internal/ncproxy"]:::network
    end

    %% Security & Extensibility
    SecurityPolicy["pkg/securitypolicy"]:::extension
    GoRunhcs["pkg/go-runhcs"]:::extension

    %% Auxiliary Tools
    subgraph "Auxiliary Tools"
        DeviceUtil["cmd/device-util"]:::tools
        JobObjUtil["cmd/jobobject-util"]:::tools
        GCSTools["cmd/gcstools"]:::tools
        MkUVM["cmd/mkuvmcim"]:::tools
        Hooks["cmd/hooks"]:::tools
        ShimDiagCLI["cmd/shimdiag"]:::tools
        ShimDiagLib["internal/shimdiag"]:::tools
    end

    %% Connections: Containerd -> Shim
    Containerd -->|"ttrpc"| ShimRunhcs1
    Containerd -->|"ttrpc"| ShimRunhcs2

    %% Shim to Host Libraries
    ShimRunhcs1 -->|calls| HCS
    ShimRunhcs2 -->|calls| HCS
    ShimRunhcs1 -->|calls| HNS
    ShimRunhcs2 -->|calls| HNS
    ShimRunhcs1 -->|calls| UVM
    ShimRunhcs1 -->|sidecar RPC| GCSHostSide
    ShimRunhcs2 -->|sidecar RPC| GCSHostSide

    %% Host Libraries to OS Services
    HCS -->|COM/REST via| WinAPI
    WinAPI -->|calls| HCSsvc
    HNS -->|COM/REST via| WinAPI
    WinAPI -->|calls| HNSsvc

    %% OS Services to Hypervisor
    HCSsvc -->|launch VM| Hypervisor
    Hypervisor -->|creates| VM
    HNSsvc -->|provisions network| VirtualSwitch["Virtual Switch"]:::network
    VirtualSwitch -->|connects| VM

    %% Inside Utility VM
    VM --> GCSGuest
    GCSGuest -->|uses| GuestLib
    GuestLib -->|vsock/named-pipe| GCSHostSide
    GCSHostSide -->|forward RPC| ShimRunhcs1

    %% Storage flows
    ShimRunhcs1 -->|storage API| CompStorage
    ShimRunhcs1 -->|layer API| WCLayerLib
    ShimRunhcs1 -->|ext4 operations| Ext4Lib
    WCLayerCLI -->|utility| WCLayerLib
    Ext4CLI -->|utility| Ext4Lib

    %% Networking flows
    ShimRunhcs1 -->|network API| HCN
    ShimRunhcs1 -->|proxy RPC| NCProxyLib
    NCProxyCLI -->|utility| NCProxyLib

    %% Security and Extensibility
    ShimRunhcs1 --> SecurityPolicy
    ShimRunhcs1 --> GoRunhcs

    %% Auxiliary
    ShimRunhcs1 --> DeviceUtil
    ShimRunhcs1 --> JobObjUtil
    ShimRunhcs1 --> GCSTools
    ShimRunhcs1 --> MkUVM
    ShimRunhcs1 --> Hooks
    ShimRunhcs1 --> ShimDiagCLI
    ShimRunhcs1 --> ShimDiagLib

    %% Click Events
    click ShimRunhcs1 "https://github.com/microsoft/hcsshim/tree/main/cmd/containerd-shim-runhcs-v1"
    click ShimRunhcs2 "https://github.com/microsoft/hcsshim/tree/main/cmd/runhcs"
    click GCSGuest "https://github.com/microsoft/hcsshim/tree/main/cmd/gcs"
    click GCSHostSide "https://github.com/microsoft/hcsshim/tree/main/cmd/gcs-sidecar"
    click HCS "https://github.com/microsoft/hcsshim/tree/main/internal/hcs"
    click HNS "https://github.com/microsoft/hcsshim/tree/main/internal/hns"
    click UVM "https://github.com/microsoft/hcsshim/tree/main/internal/uvm"
    click GuestLib "https://github.com/microsoft/hcsshim/tree/main/internal/guest"
    click GCSHostSide "https://github.com/microsoft/hcsshim/tree/main/internal/gcs-sidecar"
    click WCLayerCLI "https://github.com/microsoft/hcsshim/tree/main/cmd/wclayer"
    click WCLayerLib "https://github.com/microsoft/hcsshim/tree/main/internal/wclayer"
    click CompStorage "https://github.com/microsoft/hcsshim/tree/main/computestorage"
    click Ext4CLI "https://github.com/microsoft/hcsshim/tree/main/cmd/tar2ext4"
    click Ext4Lib "https://github.com/microsoft/hcsshim/tree/main/ext4"
    click HCN "https://github.com/microsoft/hcsshim/tree/main/hcn"
    click NCProxyCLI "https://github.com/microsoft/hcsshim/tree/main/cmd/ncproxy"
    click NCProxyLib "https://github.com/microsoft/hcsshim/tree/main/internal/ncproxy"
    click SecurityPolicy "https://github.com/microsoft/hcsshim/tree/main/pkg/securitypolicy"
    click GoRunhcs "https://github.com/microsoft/hcsshim/tree/main/pkg/go-runhcs"
    click ShimDiagCLI "https://github.com/microsoft/hcsshim/tree/main/cmd/shimdiag"
    click ShimDiagLib "https://github.com/microsoft/hcsshim/tree/main/internal/shimdiag"
    click DeviceUtil "https://github.com/microsoft/hcsshim/tree/main/cmd/device-util"
    click JobObjUtil "https://github.com/microsoft/hcsshim/tree/main/cmd/jobobject-util"
    click GCSTools "https://github.com/microsoft/hcsshim/tree/main/cmd/gcstools"
    click MkUVM "https://github.com/microsoft/hcsshim/tree/main/cmd/mkuvmcim"
    click Hooks "https://github.com/microsoft/hcsshim/tree/main/cmd/hooks"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px;
    classDef host fill:#ffebcd,stroke:#333,stroke-width:1px;
    classDef os fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef vm fill:#90ee90,stroke:#333,stroke-width:1px;
    classDef storage fill:#ffe4e1,stroke:#333,stroke-width:1px;
    classDef network fill:#e0ffff,stroke:#333,stroke-width:1px;
    classDef tools fill:#fafad2,stroke:#333,stroke-width:1px;
    classDef extension fill:#d3d3d3,stroke:#333,stroke-width:1px;
```
