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.

Implementation

Current direction is to use libkrun to boot the gateway inside a lightweight microVM, with the control plane running inside that guest rather than directly against the host container runtime. Networking can be handled through a user-mode path such as gvproxy, which gives us explicit host-to-guest port forwarding without depending on host Docker bridge behavior.

[areporeporepo]

This looks like an excellent architectural move.

Coming from the perspective of building local agent sandboxes (like OpenClaw/NemoClaw), relying on host-level Docker for the gateway constantly introduces networking edge cases and lifecycle drift depending on the user's OS and container daemon. Moving to a control-plane appliance via a microVM provides a drastically stronger security boundary without the typical VM-based GPU passthrough headaches, since the gateway mostly acts as an inference proxy (inference.local).

Looking top-down at the current architecture, I do have a few implementation considerations for this migration:

1. Guest Kernel Security Features: The current agent isolation relies on Landlock FS and Seccomp BPF. Since the microVM will use its own kernel instead of the host's, we need to ensure the custom kernel booted by libkrun is explicitly compiled with CONFIG_SECURITY_LANDLOCK=y and CONFIG_SECCOMP_FILTER=y, otherwise the sandbox security guarantees will degrade.
2. SQLite Persistence vs virtio-fs: The openshell-server StatefulSet relies on SQLite (/var/openshell/openshell.db). If the microVM uses virtio-fs to map this from the host, SQLite can sometimes suffer from locking issues or corruption across the host-guest boundary. It might be safer to use a raw virtual block device (ext4) for the data partition.
3. File Sync Throughput on gvproxy: The CLI currently relies on tar-over-SSH for file syncing. While gvproxy is fantastic for API and proxy traffic (similar to the benefits of gVisor's network stack in Modal but purely in user-space), user-mode networking can sometimes CPU-bottleneck on high-bandwidth TCP streams. Has the file sync throughput been benchmarked over gvproxy for large repositories?

Fully support the shift to libkrun for this!