TinyKVM: running Linux programs in a userspace emulator at native speed

A userspace emulator library, not a hypervisor you deploy

TinyKVM sits in an unusual place between running a program directly and running it in a virtual machine. It is a library, written in C++, that a host program embeds and uses to execute other Linux programs. There is no disk image to boot, no guest operating system to install, and no management plane around it. The unit of work is a program you already have.

The problem it addresses is specific. Imagine an HTTP cache or a web server that wants to run request-based workloads at native speed while keeping each execution contained. A full virtual machine gives containment but adds a boot, a guest kernel, and a device model to every start. Running the code in the host process gives speed but no boundary. TinyKVM is the middle option: the code runs under hardware virtualization, on the CPU, with a small API surface rather than a whole machine.

The repository belongs to Varnish Software, which is a good clue about the domain. The stated use case in the project documentation is request-based workloads in high-performance HTTP caches and web servers, where start-up cost per request matters more than the isolation of a multi-tenant guest.

The rule of thumb: if it runs locally, it runs here

The userspace framing has a direct consequence, and the project states it as a rule of thumb: if you can run a program locally on your machine, you can run it in TinyKVM, at the same speed.

The reason is that there is no translation layer. A program built on your terminal is a normal Linux binary using the ordinary instruction set and the ordinary system calls, and TinyKVM runs it on the same CPU with the same run-time and the same CPU features. There is no bytecode, no interpreter, and no cross-architecture emulation in the picture.

That is also what makes the library easy to adopt experimentally. There is no new toolchain to learn and no separate build target to reproduce in the sandbox. The binary you already test locally is the binary you embed.

The cost of that convenience shows up in the security story rather than the performance story. A library that runs a program inside your process, with the program's own system calls, sits close to the host in a way a separate virtual machine does not. The project describes the result as sandboxing, and the repository carries a guest directory, a lib directory, an src directory, a fuzz directory and a tests directory, but the README does not describe the isolation model, the syscall surface, or the security boundary in enough detail to settle the question from documentation alone.

Four differences from running the program yourself

The project is honest about the fact that running in TinyKVM is not identical to running in the terminal, and it lists four differences.

The first is an execution timeout, which allows automatic stopping of stuck programs. This is the feature that makes a per-request execution model workable at all, because a request that hangs cannot be allowed to hold resources indefinitely.

The second is memory limits. The host can cap how much the executed program is allowed to allocate, which is what makes the containment meaningful for a service that runs code on behalf of requests.

The third is forking. TinyKVM can fork an initialized program into hundreds of pre-initialized VMs, which is the mechanism that removes start-up cost from the request path. You initialise the guest once, then clone the prepared state, which is a very different cost profile from booting a fresh machine per request.

The fourth is hugepages. TinyKVM can load programs while preferring hugepages, which the documentation attributes to performance gains, since larger pages mean fewer translations for the same working set.

The four together define the shape of the library. It is designed for the case where you run the same program many times, want each execution bounded, and want the setup work to be paid once.

Hardware virtualization removes the cross-architecture headache

There is a second argument in the project documentation that has nothing to do with speed, and it is the one most infrastructure people notice first.

Building and running software for another architecture is usually a struggle. It needs a cross toolchain, it needs a matching root filesystem, and debugging it is painful. Running directly on the CPU through hardware virtualization removes that whole category of work: the program is built and run natively, on the same machine, with the same toolchain, and the virtualization boundary does the isolation rather than the instruction set doing the conversion.

The documentation calls this feature understated, and it is worth taking seriously. If your workload is a request handler that has to run somewhere else, somewhere hostile, or under a policy you do not control, being able to build it with your normal compiler changes the cost of the whole project.

There is also a forward compatibility argument. The documentation argues that as CPUs evolve, TinyKVM evolves with them: because the code runs on the real CPU rather than on an emulated one, it never has to be updated, yet it continues to run at native speeds. That reasoning holds only for the portion of the ISA that KVM exposes, which is a boundary worth keeping in mind if you need a specific instruction set extension.

The tree tells you what is missing from the README

The README for this project is short, and the repository layout carries more information than the prose does. At the top level there is a CMakeLists.txt, a lib directory for the library itself, an src directory, a guest directory, a fuzz directory, a tests directory, and a docs directory. There is also a storage.sh script, a TODO.md, a .gitmodules file, and CI configuration under .github.

A fuzz directory next to a tests directory is a meaningful signal about how the project is hardened, since fuzzing is how a parser or a syscall handler gets exercised with hostile input. The .gitmodules file means some dependencies arrive as submodules rather than as vendored source, which matters if you build in an environment without network access to those repositories.

The interesting gap is documentation of the build and the install. The README contains no build instructions, no configure step, and no example program. For a library whose selling point is that you embed it, that is a real ergonomic cost: an adopter learns the API from the docs directory and the source rather than from a getting started page. The README also points at a Contributor License Agreement and a Code of Conduct for anyone submitting a pull request.

Dual licensing, and two different versions of the GPL in the metadata

The licensing deserves careful reading, because there is an inconsistency inside the repository itself.

The licensing section of the README describes a dual model. The open source option is stated as GPL-3.0, with the licence text in the LICENSE file, and a commercial licence is available under terms controlled by Varnish Software, with the contact address [email protected] for commercial enquiries. The same dual model covers VMOD-TinyKVM, the module form of the library.

Against that, the licence field recorded for the repository is GPL-2.0. So the two places that state the licence in the repository disagree with each other, and the README is the one that describes the commercial option, which a GPL-only classification cannot express. The practical instruction is simple: the LICENSE file and the licensing section are what the project says, and anyone with a compliance obligation should confirm the terms with Varnish Software rather than relying on a metadata field, and this note is not legal advice.

For most users the distinction that matters in practice is between shipping the library in a product, where the GPL obligations attach, and using it inside a service, where the commercial terms may be the route to take.

Where TinyKVM sits against the alternatives

The alternative most teams will compare against is a full virtual machine, and the difference in approach is the whole point of the library.

A virtual machine runs a guest kernel, boots, initialises a device model, and exposes a block device or a network interface. It gives a well understood isolation boundary, and the cost is paid on every start. TinyKVM instead executes a Linux program under KVM inside the host process, with a much smaller API surface, which is why the project says it uses only a fraction of the KVM API, and why the KVM footprint in the kernel, quoted in the documentation as roughly forty thousand lines, is not something a typical application has to think about.

A second alternative is not virtualising at all and running the code in the host process with your own limits. That is faster still and gives up the containment entirely, so the trade is between the timeout and memory limits of a library like this and a full machine's isolation.

The limits of TinyKVM follow from the same design. It runs programs, not operating systems, so a workload that needs a guest kernel, a filesystem of its own, or a network stack inside the guest is out of scope. It is also a library rather than a product: there is no released version list, the repository publishes no GitHub releases, and the last push was on 2026-08-21, so an adopter is tracking a moving master branch or a submodule pin rather than a stream of tagged releases.

Editorial conclusion

TinyKVM fits teams that already have a fast native binary and want to sandbox a request path without standing up a full virtual machine, and it is the wrong tool for workloads that need a complete guest operating system or a documented isolation boundary. Verify first how the isolation model is described for your use case, because the README explains the performance angle and the four behavioural differences but not the security boundary, and read the licensing section before shipping it, since the README states GPL-3.0 while the repository licence field records GPL-2.0.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. varnish/tinykvm on GitHub