Solo5: the sandbox layer between a unikernel and a hypervisor

Middleware, and the project says so

Solo5 started as a project by Dan Williams at IBM Research to port MirageOS to run on the Linux/KVM hypervisor, and it has grown into a more general sandboxed execution environment for applications built using various unikernels, also known as library operating systems, targeting different sandboxing technologies on diverse host operating systems and hypervisors. The README is direct about the audience. As Solo5 is essentially a piece of middleware interfacing unikernel-style applications with their host systems, it is not an end-developer product as such. That sentence is the most important line in the file for an evaluator, because it defines what you are adopting. You are not installing a runtime that runs your programs. You are installing the layer that lets a program written against a specific operating system abstraction run inside a sandbox that someone else controls. The consequence is that the value is invisible until you have a unikernel, and that the interesting work happens in the ports and the bindings.

A public API for guests, tenders for hosts

The architecture has two sides, and the README explains each in terms of what it is for. On the guest side there is a public, guest-facing API, described as designed for ease of porting existing and future unikernel-native applications, and it lives in include/solo5.h. On the host side, that API facilitates the implementation of host-facing bindings and tenders, which are designed with isolation, a minimal attack surface and ease of porting to different sandboxing technologies or host systems in mind. The two halves are separate on purpose. A guest application should not know or care whether it is running under KVM, under a different hypervisor mechanism, or under something else, and the tender is the component that knows. The minimal attack surface is the other half of the isolation argument, since the host-facing side is the part that the guest can reach and therefore the part that has to be small. The trade in the design is that every additional host or sandbox technology means another tender to write and maintain, and the tree shows that cost, with a tenders/ directory and a bindings/ directory at the top level.

Why a monitor became a tender

The terminology section of the README is a small archaeology of the project's design. Since Solo5 0.4.0 the terminology changed to better reflect the intended architecture and long-term goals, and what used to be called a monitor is now called a tender. As part of that change, the ukvm target and the monitor were renamed to hvt, hardware virtualized tender, to reflect that they are no longer specific to the KVM hypervisor and to allow for the development of further tenders such as spt. The reason the rename matters is the direction of travel. A monitor named after a hypervisor is a component that can only ever be one hypervisor's monitor, and the project was trying to be several, so the vocabulary had to change before the code could. A reviewer of this repository should read the tender set as the extension point of the project, and the name change as the clearest statement of that intent.

Boot time as a design goal, and the FaaS angle

Two of the listed features are about time. The first is support for live and post-mortem debugging of unikernels, which matters because a unikernel is a small, statically linked binary with its own userland, so the usual tooling for attaching a debugger to a process does not obviously apply. The second is fast boot times, described as comparable to loading a standard user process, and it is that characteristic that the README connects to function as a service use-cases. That connection is the reason a unikernel model keeps being proposed for short-lived workloads, and Solo5 is the piece that makes a unikernel bootable on a host in the time frame a request handler needs. Whether that is useful in practice depends on the host and the workload, and the documentation for the technical overview, goals and limitations is where the project puts that argument, at docs/architecture.md.

Getting started means starting with a unikernel

The getting started section sends developers to the project they intend to use, which is the honest instruction for a middleware layer. To get started as a developer with Solo5, the README says to refer primarily to the instructions provided by the unikernel project you intend to develop applications with, pointing at MirageOS at mirage.io/docs/install and IncludeOS. The Solo5-specific documentation is listed separately and is not tied to any one unikernel: building Solo5 and running Solo5-based unikernels in docs/building.md, debugging them in docs/debugging.md, and the technical overview, goals, limitations and architecture in docs/architecture.md. The build machinery in the tree supports that layering, with a configure.sh, a GNUmakefile alongside Makefile.common, a toolchain/ directory, an elftool/ directory for manipulating the guest binaries, an opam/ directory for the packaging route, and a tests/ directory. The homepage points at the documentation rather than a product page, which is consistent with the middleware framing.

Contribution rules, including the ones about AI

The contributing section is short and specific. Solo5 is developed on GitHub and licensed under a liberal ISC license, contributions are accepted via pull requests, and when submitting one you are asked to add your details to the AUTHORS file and, if the contribution adds new source files, to copy the copyright header from an existing source file. The coding style is described as as for the Linux kernel, but with 4 spaces instead of tabs, and when in doubt to follow the style in existing source files. There is a mailing list for general development discussion at [email protected], with archives available, and a substantial contribution, a port of a new unikernel, or a general question unrelated to a specific unikernel should go to the list first:

# Subscribe to the Solo5 mailing list by sending an empty email to:
[email protected]

One rule stands out and deserves repeating for anyone reading this. The README states that contributions involving AI must comply with the rules set out in AI.md, and that if they do not comply, the project reserves the right to reject the contribution. There is an AI.md file at the root of the repository, and it is part of the contribution contract rather than an afterthought, so it is the first file to read before opening a pull request against this codebase.

Where Solo5 is the wrong tool

Four limits are clear. The first is the audience. If you want to run an ordinary Linux program with some isolation, a container or a process sandbox is the answer and Solo5 is a detour, because a Solo5 guest has to be a unikernel with a Solo5-compatible syscall surface, and porting a general program to one is a project rather than a configuration. The second is that the payoff is uneven across workloads. A short-lived, single-purpose workload that spends its life in a request handler benefits from the boot time and the small memory footprint, while a long-running service that starts once benefits from neither as much, and the minimal attack surface argument is a host-side property that only pays off if the tender is well written. The third is the maintenance surface. Every host operating system and every sandboxing technology needs a tender, and a guest needs bindings, so the matrix of things to port grows with every combination, which is a real cost for a project with a small team. The fourth is the maturity of the wider ecosystem. Solo5 itself is at version 0.13.0, released on 2026-08-28, with 0.12.1 and 0.12.0 before it, and the last push was on 2026-10-15, so the project is moving, but the number of addons in a 0.x line is a fair signal that interfaces can still change under you.

Editorial conclusion

Adopt Solo5 if you are writing or porting a unikernel and want to run the same guest on more than one host or hypervisor, and you are prepared to work at the level of bindings and tenders. Do not adopt it as a container runtime, a sandbox for ordinary Linux programs, or a way to deploy an application without writing a unikernel first. Before you start, read docs/architecture.md for the goals and limitations, pick the tender that matches your host, and check AI.md if you plan to submit code, because the project states that contributions involving AI must comply with those rules or they will be rejected.

Frequently asked questions

Official sources

1. Issues
2. License: ISC
3. README
4. Releases
5. Solo5/solo5 on GitHub