Run OpenShell Gateway Inside a Dedicated MicroVM

[drew]

We are moving the OpenShell gateway from direct host Docker integration into a dedicated microVM runtime. The implementation uses libkrun to boot a lightweight VM that runs k3s directly with containerd inside the guest, with user-mode networking handling host-to-guest connectivity instead of relying on Docker on the host.

Motivation

This would give us a cleaner architecture for both reliability and security. On the reliability side, it reduces our dependence on the host’s container runtime and networking behavior, which is where a lot of environment-specific issues tend to show up: differences across Docker implementations, bridge and port-forwarding behavior, DNS/NAT quirks, and lifecycle drift between what the gateway expects and what the host actually does. A microVM gives us a narrower, more controlled runtime boundary, so gateway startup, networking, and control-plane behavior can become much more consistent across machines.

On the security side, this is an even stronger improvement. Running the gateway inside a microVM gives us a real isolation boundary instead of relying on direct host-container integration. It also means we no longer need to depend on privileged containers for core gateway behavior, which removes a meaningful class of risk from the design. Rather than asking the host container stack for elevated access and then building around those assumptions, we can move that responsibility into a dedicated VM boundary with a more explicit and defensible security model.

At a high level, this means treating the gateway as a self-contained control-plane appliance with its own runtime, networking model, and storage model, instead of as a host process tightly coupled to Docker. Over time, the architecture should aim to reduce or eliminate Docker-specific host lifecycle logic and replace it with a VM-backed gateway runtime that is more predictable, more portable, and more secure.