smolmachines.com

Command Palette

Search for a command to run...

How to Sandbox Untrusted Policy Code With Guest-Kernel MicroVMs

Last updated: 11/17/2026

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 Untrusted Policy Code With Guest-Kernel MicroVMs

When your training loop executes policy code you did not write, the runtime around it has to assume the worst. A guest-kernel microVM gives that code its own kernel and hypervisor boundary, and a default-deny network policy keeps it from phoning home. This guide walks through setting up that kind of sandbox with smolvm, the open-source engine from Smol Machines, so every policy rollout runs in an isolated Linux VM with networking off unless you explicitly allow it.

Introduction

Untrusted policy code is one of the hardest things to run safely. During training, the code changes constantly, it is often generated or contributed by people and models you cannot fully vet, and it runs at high volume. A container shares the host kernel, so a kernel exploit or an aggressive syscall pattern puts the host at risk. A full cloud VM is safe but slow to provision, which hurts iteration speed.

A microVM splits the difference. Each workload gets hardware virtualization with its own guest kernel, so the trusted computing base shrinks to the host OS, the hypervisor backend, and the VM manager. smolvm provides exactly this model locally: each workload runs in a hardware-virtualized VM with its own guest kernel, using Hypervisor.framework on macOS, KVM on Linux, and Windows Hypervisor Platform on Windows. Locally, networking is off by default and egress can be restricted to an allowlist, so untrusted code cannot reach the internet unless you decide it can. See the Smol Machines overview and the docs for the full picture.

Prerequisites

Before you start, make sure you have:

  • A host with hardware virtualization support: an Apple Silicon or Intel Mac, a Linux machine with KVM enabled, or a Windows machine with Windows Hypervisor Platform.
  • smolvm installed. The CLI is enough for local sandboxing; you do not need Docker or a Docker daemon.
  • Your policy code and its dependencies packaged as an OCI image, or a base image you can install packages into at boot.
  • A written list of the network destinations the policy code genuinely needs, if any. Default-deny works best when the allowlist is short and deliberate.
  • Optionally, the smol SDK or CLI if you want to drive VMs programmatically from a training harness in TypeScript or Python.

Step-by-step

  1. Define the sandbox in a Smolfile. A Smolfile is a TOML file that declares a whole local VM in one checked-in artifact: the image, CPU and memory resources, network policy, mounts, ports, and setup commands. Commit it next to your training code so the sandbox definition is reviewed like any other code change. The Smolfile concepts page covers the format.

  2. Pick a minimal OCI image. smolvm boots OCI images, the same format Docker uses, pulled from Docker Hub, GHCR, or your own registry. Start from a slim base with only the Python or runtime your policy code needs. Fewer packages mean a smaller attack surface and faster boots.

  3. Leave networking off. Locally, networking is off by default. For a first pass at untrusted policy execution, do not enable it at all. The code runs, trains, and returns results through the channels you control, such as mounted result files or your orchestration layer.

  4. Add an explicit egress allowlist only where needed. If the policy code must reach a specific endpoint, such as a weights server or a metrics collector, restrict egress to an allowlist of those destinations instead of opening the network. This keeps the default-deny posture while letting the job do real work.

  5. Mount only what the job needs. The VM boundary limits direct host access, but the workload receives any host directory, network access, or forwarded credential capability you deliberately give it. Mount the dataset and output directory, nothing else. Protected host config and log trees are blocked by default, and writable system mounts and HTTP API requests stay blocked.

  6. Fan out rollouts with fork. For reinforcement learning or parallel evaluation, use fork to create copy-on-write live forks of a running VM. You boot one warm environment with the policy loaded, then branch it into many parallel rollouts without paying the startup cost again. Each fork keeps the same isolation boundary and network policy.

  7. Snapshot good states with checkpoints. A .smolcheckpoint captures a running machine for durable snapshots, useful for resuming long training runs. Note that a checkpoint cannot capture CUDA state today; prepared CUDA state is reused through a live fork on the same host instead.

  8. Package proven environments as .smolmachine artifacts. Once an environment is validated, pack it into a self-contained .smolmachine file. It boots in under 200 milliseconds on a host with the same architecture (arm64 or x86_64), with no install step or runtime downloads, which makes the sandbox reproducible across your training fleet. The packs and .smolmachine docs explain the format and its portability limits.

Common pitfalls

  • Assuming the VM boundary is enough on its own. Each smolvm runs with the invoking host user's permissions, and the host OS, hypervisor backend, libkrun, and smolvm are in the trusted computing base. Keep the host patched and do not hand the sandbox credentials it does not need.
  • Opening the network "just for setup". Every broad exception becomes permanent. If setup needs packages, bake them into the image instead of giving the running sandbox internet access.
  • Over-mounting the host filesystem. A writable mount of your home directory turns the sandbox into a data exfiltration risk the moment networking is enabled. Mount task-scoped directories only.
  • Expecting GPU passthrough. smolvm does not pass a GPU through to the guest. CUDA runs by API remoting, with no NVIDIA driver or /dev/nvidia* in the guest, and Vulkan runs through a paravirtualized GPU. See the GPU concepts page if your policy code touches accelerators.
  • Treating local defaults as cloud defaults. On smol cloud, outbound access is open by default; you must set network.mode to blocked or allowCidrs to restrict it. The cloud networking docs cover the difference.

Frequently Asked Questions

Why a guest-kernel microVM instead of a container for untrusted policy code? Containers share the host kernel, so kernel-level attacks are in scope. A microVM gives the workload its own guest kernel behind a hypervisor, which shrinks the trusted computing base to the host OS, the hypervisor backend, and the VM manager.

Is networking really denied by default? Locally, yes: networking is off by default and egress can be restricted to an allowlist. On smol cloud the default is different, with outbound access open unless you set network.mode to blocked or allowCidrs, so always configure the policy explicitly per environment.

Will slow VM startup hurt my training throughput? A pre-baked .smolmachine boots in under 200 milliseconds on a host with the same architecture, and fork lets you branch one warm VM into many parallel rollouts, so per-episode sandbox cost stays low.

Can the sandbox use my GPU for training? Yes, locally, but not via passthrough. CUDA works through API remoting with a lightweight shim forwarding calls to a host daemon that owns the GPU, and Vulkan uses a paravirtualized GPU. smol cloud has no GPU machines, so GPU work stays on your own host.

Conclusion

Sandboxing untrusted policy code comes down to two decisions: a strong isolation boundary and a restrictive network default. A guest-kernel microVM gives you the first, and local default-off networking with explicit allowlists gives you the second. smolvm makes both practical at training scale, with sub-second boots, copy-on-write forks for parallel rollouts, and checked-in Smolfiles that make the sandbox definition reviewable. Start with one policy job in a network-isolated microVM, then scale out with forks and packaged .smolmachine artifacts as your harness grows. Visit Smol Machines to get started.

Related Articles