NanaBox, a portable Hyper-V front end built on the low-level HCS API

Why it is deliberately not a Hyper-V client

The README explains the architecture in a way that is unusual for a project README, and it is worth reading closely because every other decision follows from it.

NanaBox is not a Hyper-V client because the Host Compute System API is a low-level API of the Hyper-V WMI Providers, the same ones used in Hyper-V Manager, and because HCS is stateless, which means it is not available to manage the virtual machines listed in Hyper-V Manager.

That is a precise statement of a real limitation. The higher-level interface keeps a registry of configurations, and a machine's virtual machines are entries in that registry. HCS is the execution layer underneath, and it does not own the registry. A client built on HCS can create a virtual machine, and it can find the ones it created, but it cannot see the ones somebody else created through the manager.

The author states the reason for choosing that layer anyway. NanaBox chooses HCS over the Hyper-V WMI Providers because the author, Kenji Mouri, wants to have portable virtual machine configurations, and finds the process of registering virtual machine configurations into the system disgusting.

That is a design decision with a price, and the price is interoperability with the manager. In exchange, the virtual machine definition is a file rather than a registry entry, and the project takes the position that the registry is the thing worth escaping. Anyone evaluating this has to decide whether the portability is worth giving up the shared view, and the README is clear enough that the decision can be made deliberately.

A JSON configuration format, chosen against a binary one

The second architectural decision is the configuration format, and it follows from the first. NanaBox chooses to define its own JSON-based virtual machine configuration format because Hyper-V's VMCX is a binary format with no documented format definitions from Microsoft.

That is a stronger argument than it first appears. A binary format with no published specification cannot be inspected, diffed, generated by a tool, or reviewed in a pull request. It can only be produced and consumed by the software that implements it. A JSON format can be all of those things, and for a project whose stated goal is portable configurations, that difference is the whole point.

The practical effect is that a virtual machine is described by a text file. It can live in a repository, be reviewed in a diff, be generated by a script, be templated per environment, and be copied to another machine. A configuration that is a registry entry has none of those properties, and a team that wants infrastructure as code cannot get there through a binary blob.

The repository layout supports the picture. There is a NanaBox.Core/ directory for the core library, a NanaBox/ directory for the application, a NanaBox.Project/ directory and a NanaBoxPackage/ for the packaging, a NanaBox.ProjectAssetsGenerator/ and a NanaBox.RefreshPackageVersion/ for the build pipeline, a Documents/ directory holding the design notes, and two solution files, NanaBox.slnx and NanaBox.MaintainerTools.slnx, with BuildAllTargets.cmd and BuildAllTargets.proj for building every target at once.

The JSON choice is also what makes the open source project coherent. A configuration format that is text can be documented, and a documentation file for a binary format is a description of somebody else's implementation.

The feature list is a Hyper-V capability matrix

The features section reads like a checklist of what the platform layer can do, and reading it tells you how much of the modern Hyper-V stack NanaBox exposes rather than hiding.

On the virtualisation side there is Hyper-V Enhanced Session Mode for Windows guests, nested virtualization, and the GPU paravirtualization solution, known as GPU-PV. There is support for exposing COM ports and physical drives to the virtual machine, and for enabling Secure Boot. TPM 2.0 is supported for virtual machines on a Windows 11 version 24H2 or later host, with a parenthetical note that Windows Server 2022 introduced the related HCS interfaces but they seem not to be implemented there. Partial System Management BIOS information can be customised, which is what you change to make a guest report a particular manufacturer and model. Cursor confinement with a Ctrl+Alt+Left or Right shortcut is available to improve the experience for some applications, with the same shortcut releasing it, and the relative mouse mode is enabled on a Windows 11 version 24H2 or later host.

On the shared-folder side there are two protocols, and both are the modern ones. Plan 9 protocol over Hyper-V Socket supports read-only and read-write file sharing between host and guest, and Virtual SMB, which is SMB over VMBus, does the same. A virtual switch can be customised per adapter, with suggestions for using a customised switch and for naming and subneting the switch on first creation.

On the shell side, the application is XAML-based and uses XAML Islands, which modernises the user interface and brings dark and light mode support. There is full High DPI and partial Accessibility support, full screen mode, multi-language support for English and Simplified Chinese, and the package is delivered as MSIX for a modern deployment experience.

The pattern is consistent. NanaBox does not implement a hypervisor; it surfaces the platform's, and adds the parts the platform leaves out.

The known issues show the API underneath

The known issues section is where the platform shows through, and it is honest in a way that helps a reader more than a reassuring document would.

Because of the limitations of the Host Compute System API and the Host Compute Network API, there are constraints that also apply to NanaBox. It only supports creating UEFI Class 3, or UEFI without CSM, or Hyper-V Gen 2 virtual machines, which means the legacy BIOS mode of the early Hyper-V generations is simply not reachable. NanaBox needs elevated privilege via UAC, so it is an administrator tool by construction. The automatic switch between Enhanced Session Mode and Basic Session Mode will not be implemented, which is a deliberate decision rather than an omission. And you should not put a virtual machine configuration file at the root of the drive, or you will encounter an access denied error, which is a small sharp edge in an otherwise forgiving system.

The second group of known issues is about the distribution channel rather than the virtualisation. Because of the Microsoft Store Licensing API implementation, NanaBox will try to access the internet starting with version 1.2, because it needs to do so to check the Sponsor Edition addon licensing status. To optimise the user experience it only performs that check the first time you launch, and you can click the sponsor button to refresh the status after you have purchased or redeemed the addon.

That is a small privacy-relevant behaviour stated plainly rather than buried, and a reader on a metered or offline connection deserves to know it exists before they launch the application for the first time.

The last tip in the section is a practical fix for a specific configuration. Starting with NanaBox 1.7, the application automatically configures the certificate that would normally be configured by the Virtual Machine Management Service, which is not configured when only the Virtual Machine Platform feature is enabled. On an earlier version, or if the automatic configuration fails, the README points to a script, GenerateVmmsCertificate.ps1, for doing it by hand. That is exactly the kind of note that saves an afternoon, and it only exists because somebody kept a written record of the failure.

Two channels, a store listing and a version scheme

NanaBox is distributed through the Microsoft Store and through GitHub releases, and the README carries a badge for each of the four combinations.

There is a release channel and a preview channel in the Store, with the project homepage being the release channel listing, and each has a preview listing as well. On GitHub there is a latest release badge for the release channel and one that includes prereleases for the preview channel, plus download counters for each. A single build script and a single set of artefacts serving two channels would be one thing; two channels with separate listings is a deliberate arrangement.

The version numbers are informative. The releases are 1.6.1498.0 in May 2026, 1.6.1617.0 in September, and 1.7.1633.0 later in the same month. A major component, a minor component and a build number, where the minor component moves with the release channel and the build number with the hotfix. The Store listing names the same builds in words, NanaBox 1.7 and NanaBox 1.6 Update 5, so the human-facing version and the numeric one are the same scheme seen from two angles.

The requirement set is small and modern. Windows 10 version 2004, build 19041, or later, and Windows Server 2022, build 20348, or later, on x86 64-bit and ARM 64-bit. The README says that in general NanaBox follows the 2025 baseline defined by Kenji Mouri's own document, which the reader can follow for the reasoning behind the target versions. A project that publishes the baseline it follows is easier to trust than one that picks versions case by case, because a future change to the baseline is a single decision rather than a series of them.

Sponsor Edition, and how the project sustains itself

The funding model is unusual enough to be worth a section, and the README explains it plainly rather than leaving it to be discovered.

If you want to sponsor the development of NanaBox, you are pointed to a document about NanaBox Sponsor Edition. The document also says the Sponsor Edition is free for all source code repository contributors. The general description is that NanaBox Sponsor Edition is more like a contributors' edition, and the reason is spelled out: it provides a way to purchase the honour and make someone appear as a source code contributor, because NanaBox is always a community-friendly open-source project.

That is a distinctive arrangement. Instead of selling a licence that unlocks features, the purchase buys a place in the credits, and the people who wrote the code get it for nothing. The incentive is aimed at people who want to be seen in the project rather than at people who want to use it, and for a fan-maintained reimplementation of a platform where the author has been the sole maintainer for years, that is a coherent way to widen the contributor base without closing the project to newcomers.

The second funding route is more conventional. If you would like the author to add features or improvements ahead of time, you are pointed to a page of paid services. So the project has a way to be paid for private work and a way to be paid for public status, and both are described in the README rather than buried on a website.

The rest of the community surface matches. All kinds of contributions are appreciated, and all suggestions, pull requests and issues are welcome, with a code of conduct, a contributing guide and a separate maintainer tools solution in the repository.

Where NanaBox is the wrong tool

The first limit is the one the README puts first. Because the API is stateless, NanaBox cannot manage the virtual machines that appear in Hyper-V Manager, so an administrator with an existing estate has two tools and two lists. A machine managed by the manager, and a machine managed by NanaBox, are different things with different lifecycles, and a team that expects one console to show everything will be disappointed.

The second is the platform. Windows 10 version 2004 or later, or Windows Server 2022 or later, x86 64-bit or ARM 64-bit. There is no Linux version, and no macOS version, and the technologies it exposes, the Remote Desktop ActiveX control, the XAML Islands and the MSIX packaging, are all Windows-specific by construction. This is a Windows-only tool and the alternatives for other systems are different products.

The third is the elevation requirement. NanaBox needs elevated privilege via UAC, so it cannot run as an unprivileged user, and it cannot be deployed as a per-user application in the way a store app often is. On a locked-down machine where UAC elevation is restricted, the application is simply unavailable.

The fourth is the hardware envelope. GPU paravirtualization is supported, and that is a serious feature, but it is not the same as passing a physical GPU through to a guest, which remains restricted. Nested virtualization is supported, and it is a requirement for any virtualisation-on-virtualisation setup, but it is not free and it competes with the outer host for the same hardware. A team that wants to run a GPU-accelerated workload inside a guest has to plan the nesting before the purchase, not after.

The fifth is scope of configuration. A JSON file is excellent for version control, and it means the tool owns the full definition of the machine, which is also a responsibility. There is no documented compatibility with VMCX, so a machine defined in NanaBox cannot be imported into Hyper-V Manager, and the environment-specific parts, the switches, the disks, the certificates, are all yours to keep consistent across machines.

Editorial conclusion

NanaBox fits a Windows developer or administrator who wants virtual machine definitions under version control as JSON, who wants the Hyper-V features that ship in the platform layer, such as GPU paravirtualization, nested virtualization, TPM 2.0 and Plan 9 or SMB over VMBus, and who does not need the machines to appear in Hyper-V Manager. It does not fit a user who wants one place to see all virtual machines, because the stateless API cannot enumerate what Hyper-V Manager registered, and it does not fit a non-Windows host. Before adopting it, read the known issues in the README, particularly the elevation requirement and the UEFI-only limitation, and note that since version 1.2 the application contacts the internet on first launch to check the Sponsor Edition licence status. The licence is a custom one that GitHub cannot classify, and the file is in the repository. Version 1.7.1633.0 was published on 2026-09-20 and the last push was on 2026-10-07.

Frequently asked questions

Official sources

1. Issues
2. M2Team/NanaBox on GitHub
3. Project website
4. README
5. Releases