Implement HCS driver by mie313 · Pull Request #5449 · lima-vm/lima

mie313 · 2026-08-27T11:11:35Z

What This PR Changes

This PR addresses #4961 .
It adds HCS driver as VM driver options on Windows hosts.

Linked Issue (Required in most cases)

#4961

Closes #

How I Tested This

I validated that a Linux(Ubuntu and Fedora) VM successfully launched with vmType:hcs on Windows 11 (x86_64).

AI Usage

Assisted-by: Claude
I used AI as a reference when exploring some implementation ideas and generating sample code, but I worte the actual code by myself.

AkihiroSuda · 2026-08-27T16:25:31Z

 - `tpm: true`
 - `user.passwordlessSudo` (See [Sudo](../config/sudo))
 - `External drivers`: building and using drivers as separate executables (see [Virtual Machine Drivers](../dev/drivers))
 - [`vmType: krunkit`](../config/vmtype/krunkit.md)


Move vmType:hcs around this line

AkihiroSuda · 2026-08-27T16:27:07Z

+	go.opencensus.io v0.24.0 // indirect
+)
+
+replace github.com/Microsoft/hcsshim => github.com/AkihiroSuda/hcsshim v0.0.0-20260714172934-dc466dcf888f


microsoft/hcsshim#2825 is not merged yet, so you can just copy the code from https://github.com/AkihiroSuda/hcstest.tmp/blob/28a4feaa8f5d7f1f3eba59c418a60dfc5ec048fa/main_windows.go#L76-L87 instead

Thank you, based on the file you shared, I have removed the dependency on hcsshim/internal/computecore.
I am still struggling to remove hcsshim/hcn dependency.

AkihiroSuda · 2026-08-27T16:27:19Z

+> **Warning**
+> "hcs" mode is experimental
+
+| ⚡ Requirement | Lima >= TBD + (Windows >= Windows 10 OR Windows Server 2019) |


This will be in v2.3

AkihiroSuda · 2026-08-27T16:28:00Z

+  arch: "x86_64"
+  digest: "sha256:117816726abbdefc5ef3e38902e81a76f1c76c3610e709999d0885f9d5d9b477"
+plain: true
+dns: - 8.8.8.8


YAML format seems broken for DNS

I fixed the document. (link).

AkihiroSuda · 2026-08-28T02:15:06Z

Needs rebasing

AkihiroSuda · 2026-08-28T02:15:44Z

@@ -1,4 +1,4 @@
-//go:build !external_wsl2
+//go:build windows && !external_wsl2


This line does not need to be changed

I revised the change and I update the code in main_hcs_windows.go too.

AkihiroSuda · 2026-08-28T02:15:56Z

The file name should be like main_wsl2_windows.go

Thank you, I changed the file name. I also update main_hcs.go -> main_hcs_windows.go.

AkihiroSuda · 2026-08-28T02:17:15Z

+	go.opencensus.io v0.24.0 // indirect
+)
+
+replace github.com/Microsoft/hcsshim => github.com/AkihiroSuda/hcsshim v0.0.0-20260714172934-dc466dcf888f


This replace should not longer be needed

AkihiroSuda · 2026-08-28T02:18:10Z

+> **Warning**
+> "hcs" mode is experimental
+
+| ⚡ Requirement | Lima >= 2.3 + (Windows >= Windows 10 OR Windows Server 2019) |


No need to support Windows 10 and its server derivative

I updated the requirement to Windows >= 11, since that's the only OS I have tested on.
Please let me know if Windows Server 2022 should be included here.

AkihiroSuda · 2026-08-28T20:50:54Z

 	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/sabhiram/go-gitignore v0.0.0-20210923224102-525f6e181f06 // indirect
-	github.com/segmentio/asm v1.1.3 // indirect
+	github.com/segmentio/asm v1.2.1 // indirect


LICENSE CHANGE: MIT to MIT-0 (No Attribution) segmentio/asm#86

You need to update the license list to allow MIT-0:

lima/hack/allowed-licenses.txt

Line 1 in fa0f5f6

Apache-2.0,BSD-2-Clause,BSD-2-Clause-FreeBSD,BSD-3-Clause,MIT,ISC,Python-2.0,PostgreSQL,X11,Zlib

CNCF has already approved MIT-0:
https://github.com/cncf/foundation/blob/87e70a07d5a0cf06cd6f8208b8d52c16f035724a/policies-guidance/allowed-third-party-license-policy.md?plain=1#L53

go-licenses still doesn't seem to support MIT-0

Add MIT-0 (MIT No Attribution) license support google/licenseclassifier#75

So you can just add --ignore

lima/Makefile

Lines 645 to 650 in fa0f5f6

.PHONY: go-licenses

go-licenses:

# the allow list corresponds to https://github.com/cncf/foundation/blob/e5db022a0009f4db52b89d9875640cf3137153fe/allowed-third-party-license-policy.md

# hashicorp/hcl/v2 is MPL-2.0; covered by the CNCF license exception for hashicorp/hcl

# see also https://github.com/cncf/foundation/issues/1242

go-licenses check --include_tests --ignore github.com/hashicorp/hcl/v2 ./... --allowed_licenses=$$(cat ./hack/allowed-licenses.txt)

AkihiroSuda · 2026-08-28T20:51:50Z


 require github.com/clipperhouse/uax29/v2 v2.2.0 // indirect
+
+require github.com/Microsoft/hcsshim v0.14.1


nit: merge to the existing require () block

AkihiroSuda · 2026-08-28T20:51:58Z

+
+require github.com/Microsoft/hcsshim v0.14.1
+
+require (


nit: merge to the existing indirect require () block

AkihiroSuda · 2026-08-28T20:52:11Z

@@ -0,0 +1,10 @@
+//go:build windows


Unneeded line

AkihiroSuda · 2026-08-28T23:19:23Z

-	# the allow list corresponds to https://github.com/cncf/foundation/blob/e5db022a0009f4db52b89d9875640cf3137153fe/allowed-third-party-license-policy.md
+	# the allow list corresponds to https://github.com/cncf/foundation/blob/87e70a07d5a0cf06cd6f8208b8d52c16f035724a/policies-guidance/allowed-third-party-license-policy.md
 	# hashicorp/hcl/v2 is MPL-2.0; covered by the CNCF license exception for hashicorp/hcl
 	# see also https://github.com/cncf/foundation/issues/1242


Add a comment line to explain the reason of ignoring github.com/segmentio/asm

AkihiroSuda

Thanks

unsuman · 2026-08-29T10:35:37Z

Should we not build it as an external driver? Since it's experimental

[EDIT]: I also see you have built the HCS driver as external below, but lima prioritises the one which is built as internal

I thought that I have not built the HCS driver as external, because cmd/limactl/main_hcs_windows.go is only built when !external_hcs is true and I have not created cmd/lima-driver-hcs/main.go. Am I wrong?

My bad I didn't see that! But I think for now building HCS as internal is OK, because external driver transport is not well tested on Windows and can have some bug(s).

unsuman · 2026-08-29T10:57:46Z

+		for range 50 {
+			e, err := hcn.GetEndpointByName(endpointName(inst.Name))
+			if err != nil {
+				logrus.Errorf("error: %s", err.Error())


Needs a break or continue

unsuman · 2026-08-29T11:16:34Z

+	}
+	if state == "Running" {
+		inst.Status = limatype.StatusRunning
+		for range 50 {


But why are we iterating for 100s here? If the state is running then we should just try to retrieve the IP once and error out if we don't get one

Thank you, you are completely right.
I have removed the for loop as you suggested.

unsuman · 2026-08-29T11:35:22Z

 	if o.HostResolver.Enabled != nil {
 		y.HostResolver.Enabled = o.HostResolver.Enabled
 	}
-	if y.HostResolver.Enabled == nil {


Other drivers code are not updated to fill this value. I think we should keep the global default and have the HCS driver override

HostResolver.Enabled value was only referred to in pkg/cidata/cidata.go and pkg/hostagent/hostagent.go.
They are replaced by the helper function HostResolverEnabled() (here)
So, I think the behavior in other drivers remains the same as before.

After double-checking, I noticed that HostResolver.Enabled is also referred to in pkg/limayaml/validate.go .
So, I have update the code as follows:
[EDIT]

if y.VMType != nil && *y.VMType == limatype.HCS { if y.HostResolver.Enabled != nil && *y.HostResolver.Enabled && len(y.DNS) > 0 { errs = errors.Join(errs, errors.New("field `dns` must be empty when field `HostResolver.Enabled` is true")) } } else { if HostResolverEnabled(y) && len(y.DNS) > 0 { errs = errors.Join(errs, errors.New("field `dns` must be empty when field `HostResolver.Enabled` is true")) } }

Thank you for pointing that out.

Signed-off-by: mie313 <mie313.tanaka@gmail.com>

unsuman

Thanks

AkihiroSuda

Thanks

mie313 force-pushed the hcs-driver branch 4 times, most recently from 2feeeef to e8a71dd Compare August 27, 2026 13:14

AkihiroSuda reviewed Aug 27, 2026

View reviewed changes

AkihiroSuda added host/Windows lfx-mentorship/2026-02 labels Aug 27, 2026

AkihiroSuda added this to the v2.3.0 milestone Aug 27, 2026

AkihiroSuda added the impact/changelog label Aug 27, 2026

AkihiroSuda reviewed Aug 28, 2026

View reviewed changes

mie313 force-pushed the hcs-driver branch 3 times, most recently from 8c3a3c5 to 1a673c7 Compare August 28, 2026 14:42

AkihiroSuda reviewed Aug 28, 2026

View reviewed changes

mie313 force-pushed the hcs-driver branch from 7dfb0fd to cc8f132 Compare August 28, 2026 23:12

AkihiroSuda reviewed Aug 28, 2026

View reviewed changes

mie313 force-pushed the hcs-driver branch from cc8f132 to eb6e5a4 Compare August 28, 2026 23:33

mie313 marked this pull request as ready for review August 28, 2026 23:44

AkihiroSuda previously approved these changes Aug 29, 2026

View reviewed changes

AkihiroSuda linked an issue Aug 29, 2026 that may be closed by this pull request

Support for Windows hosts, without depending on QEMU #4961

Closed

AkihiroSuda requested a review from unsuman August 29, 2026 00:18

unsuman reviewed Aug 29, 2026

View reviewed changes

mie313 dismissed AkihiroSuda’s stale review via 3fbc9c4 August 30, 2026 11:42

mie313 force-pushed the hcs-driver branch 2 times, most recently from 3fbc9c4 to c532ab6 Compare August 30, 2026 12:35

Implement HCS driver

15463f7

Signed-off-by: mie313 <mie313.tanaka@gmail.com>

mie313 force-pushed the hcs-driver branch from c532ab6 to 15463f7 Compare August 30, 2026 14:13

AkihiroSuda requested a review from unsuman August 31, 2026 11:34

unsuman approved these changes Aug 31, 2026

View reviewed changes

AkihiroSuda approved these changes Sep 1, 2026

View reviewed changes

AkihiroSuda merged commit dd909d0 into lima-vm:master Sep 1, 2026
62 of 64 checks passed

		@@ -1,4 +1,4 @@
		//go:build !external_wsl2
		//go:build windows && !external_wsl2

	.PHONY: go-licenses
	go-licenses:
	# the allow list corresponds to https://github.com/cncf/foundation/blob/e5db022a0009f4db52b89d9875640cf3137153fe/allowed-third-party-license-policy.md
	# hashicorp/hcl/v2 is MPL-2.0; covered by the CNCF license exception for hashicorp/hcl
	# see also https://github.com/cncf/foundation/issues/1242
	go-licenses check --include_tests --ignore github.com/hashicorp/hcl/v2 ./... --allowed_licenses=$$(cat ./hack/allowed-licenses.txt)


		require github.com/clipperhouse/uax29/v2 v2.2.0 // indirect

		require github.com/Microsoft/hcsshim v0.14.1

Uh oh!

Conversation

mie313 commented Aug 27, 2026

What This PR Changes

Linked Issue (Required in most cases)

How I Tested This

AI Usage

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda commented Aug 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mie313 Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda left a comment

Choose a reason for hiding this comment

Uh oh!

unsuman Aug 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mie313 Aug 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

unsuman left a comment

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda left a comment

Choose a reason for hiding this comment

mie313 Aug 28, 2026 •

edited

Loading

unsuman Aug 29, 2026 •

edited

Loading

mie313 Aug 30, 2026 •

edited

Loading