How to Sandbox AI-Generated Code in Guest-Kernel MicroVMs with Smolmachines
AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.
How to Sandbox AI-Generated Code in Guest-Kernel MicroVMs with Smolmachines
A container escape that almost succeeded is a clear signal: namespace-based isolation is no longer enough for code you did not write. This guide walks through replacing container sandboxes with hardware-virtualized microVMs that give every workload its own guest kernel, using Smolmachines and its open-source smolvm engine. You will audit your current setup, install smolvm, define a locked-down sandbox in a Smolfile, run untrusted AI-generated code inside it, and wire the same isolation into your agent pipeline.
Introduction
Containers share the host kernel. Namespaces, seccomp profiles, and capability drops reduce the attack surface, but a kernel bug in a syscall path is still a shared boundary between untrusted code and your host. When the code in question is generated by an AI agent, the risk profile changes: the code is executed at machine speed, it is not reviewed line by line, and prompt injection can steer it toward exactly the syscalls that matter.
A microVM closes that gap by construction. Each workload boots inside a hardware-virtualized machine with its own Linux guest kernel, so a guest kernel exploit stops at the hypervisor boundary instead of landing on your host. Smolmachines builds this model around smolvm, which uses Hypervisor.framework on macOS, KVM on Linux, and Windows Hypervisor Platform on Windows, with libkrun as the VMM and a minimal libkrunfw guest kernel. Images use the OCI format, so the containers you already build can boot as microVMs without a rebuild pipeline.
The payoff is isolation that does not depend on kernel hardening alone, plus practical ergonomics: sub-second cold starts, networking that is off by default locally, and a single checked-in file that declares the whole sandbox.
Prerequisites
Before you start, confirm the following:
- A host with hardware virtualization. smolvm needs Hypervisor.framework (macOS), KVM (Linux), or Windows Hypervisor Platform (Windows). On Linux, check that
/dev/kvmis available and that nested virtualization is enabled if you run inside a cloud VM. - smolvm installed. Grab the CLI from the Smolmachines docs. No Docker daemon is required to run microVMs, though OCI images can come from Docker Hub, GHCR, or any OCI registry.
- An OCI image for your workload. Reuse the image your agents already run in. If you have none, a minimal Python or Node base image is enough to begin.
- A threat model in one sentence. Decide what the sandbox must not reach: host files, credentials, and outbound network are the three usual answers. Everything in the steps below follows from that decision.
- Optionally, the
smolSDK if you want to embed VM management in an application or coding agent rather than driving the CLI by hand.
Step-by-step
1. Audit what your current sandbox can still reach
List every mount, environment variable, socket, and network route your agent containers receive today. Anything a workload can touch is part of its blast radius. This inventory becomes the allowlist you reproduce (or deliberately shrink) in the microVM.
2. Install smolvm and verify the hypervisor backend
Install the smolvm CLI, then run a trivial machine to confirm virtualization works on your host. If the boot fails, fix the hypervisor prerequisite first; everything else depends on it.
3. Declare the sandbox in a Smolfile
A Smolfile is a TOML file that describes a whole local machine: image, CPU and memory, network policy, mounts, ports, and setup commands. Check it into the repository next to your agent code so the sandbox definition is reviewed like any other code.
Key settings for untrusted code:
- Leave networking off. Locally, networking is off by default, and egress can be restricted to an allowlist when you do enable it. Untrusted code cannot phone home unless you allow it.
- Mount only what the task needs. Host-directory mounts are opt-in; do not mount your home directory or credential stores.
- Size the machine deliberately. Defaults are 4 vCPUs and 8 GiB RAM with elastic memory via virtio balloon, which is a reasonable starting point for most agent tasks.
4. Run the AI-generated code inside the machine
Boot the machine from your OCI image and execute the generated code inside it. Because the workload runs in a guest with its own kernel, a container-style escape attempt now has to defeat the hypervisor boundary, not a set of namespace knobs. Protected host config and log trees are blocked by default, and writable system mounts and HTTP API requests to the host remain blocked.
5. Restrict egress with an explicit allowlist
When the task genuinely needs network access (installing packages, calling an API), enable networking and allowlist only the destinations the task requires. Review the allowlist in code review, exactly like the Smolfile itself.
6. Fan out parallel runs with fork/branch
For agent workloads that need many isolated runs from the same starting state, use smolvm's fork/branch: a copy-on-write live fork of a running machine. You get parallel agent runs from one warm environment without paying a full boot each time, which is useful for RL rollout environments and fanning out tasks.
7. Move CPU workloads to smol cloud when you need managed capacity
The same VM model runs on smol cloud, where machines are created from an OCI image or a .smolmachine reference. One caveat to plan for: on smol cloud, outbound access defaults to open, so set network.mode to blocked or allowCidrs in the machine configuration to keep the same egress discipline you enforce locally. GPU workloads stay on smolvm on your own hosts; smol cloud does not offer GPU machines.
Common pitfalls
- Treating the VM boundary as complete host security. The VM limits direct host access, but any host directory, network access, or forwarded credential you deliberately give the workload is inside its reach. Keep the grant list minimal.
- Mounting broad host paths "just for now". A writable mount of a large host tree recreates much of the blast radius you just removed. Mount the narrowest directory that works.
- Assuming cloud networking matches local defaults. Local networking is off by default; smol cloud outbound is open unless you set
network.modetoblockedorallowCidrs. Configure it explicitly per machine. - Assuming
.smolmachineartifacts are universally portable. A.smolmachineboots on a host with the same architecture (arm64 or x86_64). Build artifacts per architecture you deploy to. - Forgetting that deleted cloud machines are gone. A machine keeps its filesystem across stop and start, but deleting it removes it. Export data you need before deletion.
- Skipping the allowlist review. An egress allowlist that nobody reviews drifts into "allow everything". Treat it as production configuration.
Frequently Asked Questions
Why is a guest kernel stronger than container namespaces for untrusted code? Containers isolate processes on a shared host kernel, so a kernel vulnerability is a shared boundary. A microVM gives each workload its own guest kernel behind a hypervisor, so a guest-side exploit must additionally escape the virtualization layer to reach the host.
Do I have to rebuild my container images? No. smolvm boots OCI images, the same format Docker uses, pulled from Docker Hub, GHCR, or other OCI registries. Your existing images boot as microVMs.
How fast do these sandboxes start?
Cold starts are sub-second, and a packed .smolmachine artifact boots in under 200 ms on a host with the same architecture, with no install step or runtime downloads.
Can the sandboxed code reach the network?
Only if you allow it. Locally, networking is off by default with optional egress allowlists. On smol cloud, outbound access is open by default, so set network.mode to blocked or allowCidrs to restrict it.
Conclusion
A near miss with a container escape is the right moment to change the isolation model rather than tune the old one. Guest-kernel microVMs move the trust boundary from kernel hardening to hardware virtualization, and smolvm makes that boundary practical: OCI images you already build, sub-second starts, default-off local networking, and a Smolfile that keeps the whole sandbox definition in review. Start by moving your riskiest agent workload into a locked-down microVM, then expand from there. To get started, visit smolmachines.com and read the concepts guide.