microsoft/hcsshim

microsoft/hcsshim

Description: Windows - Host Compute Service Shim

Language: Go

License: MIT

Stars: 678

Forks: 289

Open issues: 137

Created: 2015-06-29T16:44:26Z

Pushed: 2026-06-08T06:59:56Z

Default branch: main

Fork: no

Archived: no

README:

hcsshim


This package contains the Golang interface for using the Windows Host Compute Service (HCS) to launch and manage Windows Containers. It also contains other helpers and functions for managing Windows Containers such as the Golang interface for the Host Network Service (HNS), as well as code for the [guest agent](./internal/guest/README.md) (commonly referred to as the GCS or Guest Compute Service in the codebase) used to support running Linux Hyper-V containers.

It is primarily used in the Moby and Containerd projects, but it can be freely used by other projects as well.

Building

While this repository can be used as a library of sorts to call the HCS apis, there are a couple binaries built out of the repository as well. The main ones being the Linux guest agent, and an implementation of the runtime v2 containerd shim api.

Linux Hyper-V Container Guest Agent

To build the Linux guest agent itself all that's needed is to set your GOOS to "Linux" and build out of ./cmd/gcs.

C:\> $env:GOOS="linux"
C:\> go build .\cmd\gcs\

or on a Linux machine

> go build ./cmd/gcs

If you want it to be packaged inside of a rootfs to boot with alongside all of the other tools then you'll need to provide a rootfs that it can be packaged inside of. An easy way is to export the rootfs of a container.

docker pull busybox
docker run --name base_image_container busybox
docker export base_image_container | gzip > base.tar.gz
BASE=./base.tar.gz
make all

If the build is successful, in the ./out folder you should see:

> ls ./out/
delta.tar.gz initrd.img rootfs.tar.gz

Containerd Shim

For info on the Runtime V2 API.

Contrary to the typical Linux architecture of shim -> runc, the runhcs shim is used both to launch and manage the lifetime of containers.

C:\> $env:GOOS="windows"
C:\> go build .\cmd\containerd-shim-runhcs-v1

Then place the binary in the same directory that Containerd is located at in your environment. A default Containerd configuration file can be generated by running:

.\containerd.exe config default | Out-File "C:\Program Files\containerd\config.toml" -Encoding ascii

This config file will already have the shim set as the default runtime for cri interactions.

To trial using the shim out with ctr.exe:

C:\> ctr.exe run --runtime io.containerd.runhcs.v1 --rm mcr.microsoft.com/windows/nanoserver:2004 windows-test cmd /c "echo Hello World!"

Containerd Shim V2

The V2 shims are the rewrite of the Windows containerd shim. The V1 shim ([containerd-shim-runhcs-v1](./cmd/containerd-shim-runhcs-v1)) is a single, monolithic binary that handles LCOW (Linux Containers on Windows), Hyper-V WCOW (Windows Containers on Windows), process-isolated WCOW and host-process containers. In the V2 model that monolith is split into focused, per-platform shims, each backed 1:1 by a sandbox.

V2 shims are used with containerd in the same way as the V1 shim, but the API surface they expose is different. The V1 shim implemented only the containerd Task API, and used it to manage both the sandbox lifecycle and the container/process (task) lifecycle through a single service. Each V2 shim instead splits these responsibilities across the two APIs that containerd now provides for this purpose: the Sandbox API is used to manage the sandbox, while the Task API is used to manage containers and processes running inside it. Internally each V2 shim implements these as separate sandbox and task services, alongside an auxiliary shimdiag service used for diagnostics.

All three shims honor the same CRI pod model. A task annotated with "io.kubernetes.cri.container-type": "sandbox" is treated as the pause/infra container that creates the pod; sibling workload tasks set "io.kubernetes.cri.container-type": "container" and reference their pause via "io.kubernetes.cri.sandbox-id". What a "sandbox" *physically* corresponds to depends on the shim, and is described in each subsection below.

containerd-shim-lcow-v2

• Purpose: Runs Linux Containers on Windows (LCOW) — a Linux utility VM hosting Linux

containers.

• Sandbox: The Linux UVM. Each shim instance is backed 1:1 by a single UVM. This shim supports running

*multiple pods in the same UVM*, so a single shim instance may host more than one CRI pods.

• Tasks: Linux containers and processes running inside the UVM, identified via the

same CRI annotations described above.

• Implementation: [./cmd/containerd-shim-lcow-v2](./cmd/containerd-shim-lcow-v2).
• Build Tag: lcow
• Platform requirement: Windows Server 2025 (build 26100) or later.

containerd-shim-wcow-v2

• Purpose: Runs Hyper-V isolated Windows containers (WCOW) — a Windows utility VM hosting

Process and/or Host Process Containers inside it.

• Sandbox: The Windows utility VM (UVM). Each shim instance is backed 1:1 by a single UVM.
• Tasks: the Windows containers and processes running inside the UVM, identified

via the standard CRI annotations described above.

• Implementation: coming soon.
• Build Tag: wcow

containerd-shim-process-v2

• Purpose: Runs Process-isolated Windows Server containers and Host

Process Containers — workloads that execute directly on the host with no utility VM.

• Sandbox: A *pause container*. The pause container is a minimal, long-lived

container that owns…