smolvm - Mirage

smolvm boots a hardware-isolated microVM with its own guest kernel on Hypervisor.framework (macOS), KVM (Linux), or WHP (Windows). Mirage connects to a machine you created; it never starts or deletes one. See the Sandbox overview for the shared image and workspace-mount setup.

Start the machine

smolvm machine create --net --name mirage-box --image my-mirage-image
smolvm machine start --name mirage-box
smolvm machine exec --name mirage-box -- mirage workspace create /tmp/sandbox.yaml

Host directories reach the guest only if you pass them at boot with --volume; the guest otherwise sees nothing from the host filesystem.

Connect from Python

from mirage import MountMode, Workspace
from mirage.runtime.sandbox.smolvm import SmolvmRuntime

runtime = SmolvmRuntime(captures=["python3"],
                        config={"machine": "mirage-box"})
ws = Workspace({"/data": ...}, mode=MountMode.EXEC,
               runtimes=[runtime, "vfs"])
await ws.execute("python3 job.py", cwd="/data")

The smolvm CLI is the transport, so there is no SDK dependency or Mirage extra. The first captured line checks machine status and accepts only running. A stopped or created machine needs machine start; unreachable means its guest agent is not answering; frozen is a fork base, so point Mirage at a clone instead.

One machine is one guest. Concurrent lines sent to the same machine share its filesystem and process table. Give each tenant its own machine when workload-to-workload isolation matters.

Mirage timeouts stop waiting for the command; they do not kill the process inside the microVM. See Resource limits.