Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt

Use this file to discover all available pages before exploring further.

SmolVM can boot a Windows 11 sandbox alongside its Linux sandboxes. You bring a pre-installed Windows disk image (a .qcow2 file), and SmolVM handles the firmware, virtual TPM, and QEMU wiring for you. This guide explains when to use Windows guests, what you need before you start, and how to launch one.
Windows guest support is the first phase of a larger effort. Today it boots an existing Windows 11 image on Linux hosts. Building the image from an ISO, SSH-into-Windows automation, host mounts, network controls, and snapshots are not yet supported — see Current limitations.

​
What this is

A Windows sandbox is a virtual machine that runs the real Windows 11 operating system instead of Linux. You’d reach for it when:
  • You’re testing software that only ships for Windows.
  • You’re building an agent that needs to drive a Windows desktop or Windows-only application.
  • You want a disposable Windows environment that won’t touch your host machine.
The Windows VM boots the same way Linux sandboxes do — with SmolVM(...) in Python — and is isolated from your host using KVM hardware virtualization.

​
Before you start

You need three things on the host:
  1. A Linux host with KVM. Windows guests use QEMU + KVM. macOS hosts are not supported yet.
  2. A pre-installed Windows 11 qcow2 disk image. SmolVM does not build one for you in this release. You can install Windows 11 once into a qcow2 using QEMU directly, then point SmolVM at that file.
  3. OVMF (UEFI firmware) and swtpm (software TPM). Windows 11 requires UEFI Secure Boot and TPM 2.0. SmolVM looks for OVMF in the standard distro install paths and will tell you exactly which package to install if it’s missing.
Quick install of the prerequisites: 
sudo apt-get install qemu-system-x86 ovmf swtpm

​
Launch a Windows sandbox

Point SmolVM at your Windows qcow2 file and pass os="windows": 
from smolvm import SmolVM

with SmolVM(
    os="windows",
    image="~/win11-vm/disk-baseline.qcow2",
    memory=4096,
) as vm:
    print(vm.vm_id)
    # The VM is now running Windows 11.
    # Stop / delete happens automatically on context exit.
What happens behind the scenes:
  • SmolVM copies the OVMF UEFI variable store to a per-VM location so the firmware can persist boot order independently.
  • It starts a per-VM swtpm software TPM 2.0 process.
  • It launches QEMU with the right machine type (q35), Hyper-V enlightenments for performance, and a virtio-scsi root disk.
  • On stop() or delete(), the swtpm sidecar and per-VM firmware state are cleaned up.

​
Accepted image paths

image= accepts any of these for Windows guests:
  • An absolute path: image="/var/lib/vms/win11.qcow2"
  • A tilde-relative path: image="~/win11-vm/disk.qcow2"
  • A file:// URI: image="file:///var/lib/vms/win11.qcow2"
S3 URIs work too, but in this release only the local-path form is meaningful for Windows — there is no published Windows image yet.

​
Memory defaults

Windows 11 defaults to 4096 MiB of RAM in SmolVM. The minimum that boots is 2 GiB, but Edge and Defender want more. Override with memory=: 
SmolVM(os="windows", image="~/win11-vm/disk.qcow2", memory=8192)

​
How os= and image= work together

SmolVM uses two slightly different rules depending on where the image comes from:
Image sourcePass os=?Why
Local file (path or file://)YesThe file alone doesn’t tell SmolVM which OS is inside.
Published S3 imageNoThe image manifest already records the OS — passing os= errors.
For Windows today, you always use the local-file form, so always pass os="windows".

​
Current limitations

The first release of Windows guest support is deliberately narrow. The following raise a clear error rather than silently misbehaving:
  • Linux hosts only. macOS support comes in a later phase.
  • No mounts=. Host directory mounts (virtio-9p) are Linux-guest only for now.
  • No internet_settings=. Domain allowlists and egress controls are not yet wired into the Windows network stack.
  • No snapshots. vm.snapshot() and SmolVM.from_snapshot() are rejected for Windows VMs — Windows guests use multiple state artifacts (qcow2 + UEFI vars + TPM state) that can’t be checkpointed atomically yet.
  • No SSH vm.run(...). Command execution over SSH is a Linux-guest feature; on Windows you interact with the VM through its desktop.
  • You bring the image. SmolVM does not build a Windows qcow2 from an ISO for you in this release.
If you call any of the unsupported features, SmolVM raises ValueError with a plain-English message naming the feature and the workaround.

​
Troubleshooting

SmolVM probes the four standard install paths (Debian, Fedora, Arch, Homebrew). If none match, it raises a ValueError naming the package to install. Re-run after installing the ovmf / edk2-ovmf package from the table above.
Install the swtpm package from your distro. The error message includes the install hint.
image= must point at an existing .qcow2 file. Tilde and relative paths are expanded against your current working directory.
You passed os="windows" without image=. SmolVM does not build a Windows image for you yet — point at a qcow2 you’ve already installed Windows into.

​
Next steps

Backends

Why Windows guests run on QEMU

VMConfig

The full configuration model, including guest_os

SmolVM API

All constructor arguments, including os= and image=

VM lifecycle

Start, stop, and delete sandboxes
Last modified on May 25, 2026