Set up microVM isolation

For: cluster operators.

Configure the supported microVM path for the node platform.

microVMs

A microVM boots a tool's container image with a Linux kernel of its own, in a virtual machine per server. A tool that escapes its MCP server is inside that kernel; to reach the node it must break the kernel and then the virtual machine monitor, and on Linux the monitor itself runs in tier 1. It is the strongest isolation OZ0 has, and the slowest to start: about a second and a half per server here, against a fifth of a second for the same image in Docker.

A tool asks for one in its manifest. Its plugin's agents then require isolation.microvm=ready (and the image's architecture), not runtime.oci=ready: a microVM node needs no Docker.

tools:
  - id: acme_fetch
    package: oci:ghcr.io/acme/fetch-mcp@sha256:4f6c0d1b5e8a…
    isolation: microvm                # boots in a VM of its own, never in a container
    container: {memory_mb: 512, cpus: 1}

A node without microVMs leaves the tool out, Docker or not (it runs only in a microVM, which this node does not offer (...)). A tenant's --oci gvisor requirement does not apply to such a tool: it runs in its VM.

Set up a Linux node

1. Give the node's user /dev/kvm: sudo usermod -aG kvm <user> (log in again, or restart the node's service).
2. Download smolvm 1.24.0 for your architecture from its GitHub releases (smolvm-1.24.0-linux-x86_64.tar.gz or -linux-arm64.tar.gz), check its SHA-256 against the table below (smolvm's releases are not signed), and unpack it somewhere the node's user can read but not write, such as /opt/smolvm.
3. Put its smolvm on the node's PATH (ln -s /opt/smolvm-1.24.0-linux-x86_64/smolvm /usr/local/bin/smolvm), or name the folder: OZ0_MICROVM=/opt/smolvm-1.24.0-linux-x86_64 oz0-node run.
4. Restart the node. It checks every file of smolvm it loads against the release it pins, boots one VM inside tier 1, and logs smolvm booted inside tier 1; the edge labels it isolation.microvm=ready, and oz0 node show <node> and the Nodes page have a MicroVMs line. orchestrator-zero-node sandbox vm --probe --guest "$(command -v orchestrator-zero-node)" asks the same without starting the node. The first start takes about ten seconds more (smolvm unpacks its disk templates once), later ones a second and a half.

A smolvm the node binary does not pin is refused: smolvm is not a release this node pins, so it does not run it (...). Naming its folder with OZ0_MICROVM runs it anyway, and the node's facts then say pinned: false with a warning. OZ0_MICROVM=off turns microVMs off. A node whose test VM does not boot inside tier 1 (no tier 1, no access to /dev/kvm, a kernel or bubblewrap that refuses it) offers no microVMs and says why in its log and in oz0 node show --json (facts.microvm.reason). OZ0 never downloads or updates smolvm.

How a tool runs in one

orchestrator-zero-node sandbox vm starts each server's VM: smolvm machine create, start, exec with the tool's MCP over its input and output, and delete, whatever ended it: the tool, the end of its input, a cancelled call (which stops a job's server), or the node stopping.

macOS 26

Install Apple's container 1.5.0 or later (its signed installer, from its GitHub releases), and run container system start in the node's user session.

The node finds container on PATH, checks its version and that its services answer, and runs each tool with container run --rm --network none --read-only --cap-drop ALL, the node's user, whole CPUs, --ulimit nproc (

Apple's runtime has no process limit), and with egress the egress proxy's socket file and the node binary.

Apple's runtime has no no-new-privileges, and its VMs are started by its own launchd services, so they are not inside tier 1: their kernel is the boundary.

The CLI starts with a clean environment (CVE-2026-64786), and the tool's variables reach it only in an env file only the node's user may read, removed when the tool stops (a value with a line break is refused).

A Mac that has Apple's container fetches the Linux node binary the VM's bridge needs from its edge, by the release's signed manifest, of its own version only, after it found the runtime (a Mac without it, an Intel Mac and a Windows node never fetch it); a node built without a release key has no microVMs.

Older versions' copies under <data dir>/microvm/guest/ are removed at the node's start.

Neither macOS path has run on a Mac yet: scripts/test-macos-microvm.sh checks one.

What is tested

make e2e-oci-tools runs a microVM node where /dev/kvm exists. A node without Docker, in a container given /dev/kvm, finds smolvm on its PATH, checks its pins and boots it inside tier 1. The plugin's microVM tools run there alone; a node with Docker leaves them out.

The check verifies that the guest has its own kernel and no network without egress. Its only write visible to the host is in its work folder. An allowed host is reachable through the proxy's socket and another is refused. The monitor shows tier 1's seccomp filter and smolvm's, no capabilities and no new privileges. Stopping the node takes its VMs with it. OZ0_E2E_MICROVM=0 skips the check.

Earlier section link