How to Run Linux MicroVMs Without Docker with Smol Machines
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 Run Linux MicroVMs Without Docker with Smol Machines
Small teams that need isolated Linux environments do not have to install and babysit a Docker daemon to get them. Smol Machines gives you a supported hypervisor path: each workload runs in a hardware-virtualized microVM with its own guest kernel, backed by Hypervisor.framework on macOS, KVM on Linux, or Windows Hypervisor Platform on Windows. You get isolation by default, sub-second cold starts, and a single CLI that works the same way on every developer laptop. This guide walks through the full setup, from prerequisites to a running sandbox, plus the pitfalls that trip up most first deployments.
Introduction
Containers share the host kernel, so running them safely usually means running a daemon, configuring namespaces and cgroups carefully, and trusting a shared kernel boundary. For teams running AI coding agents, untrusted code, or CI jobs, that tradeoff is uncomfortable. A microVM flips it: every workload gets its own kernel, isolated by the hypervisor, with no host daemon to install, upgrade, or secure.
Smol Machines builds exactly this. The open-source smolvm engine and CLI run isolated Linux VMs locally with no Docker daemon required, and the managed smol cloud service runs the same VM model on persistent cloud machines when you do not want to manage hypervisors at all. Because both sides use the same VM model and OCI images, a workload proven locally can move to the cloud without retooling.
This guide takes you from a clean laptop to a running, isolated Linux environment, and shows how to avoid the mistakes that cost teams the most time.
Prerequisites
Before you start, confirm the following:
- A host with hardware virtualization. smolvm uses libkrun as the VMM with a libkrunfw guest kernel, backed by Hypervisor.framework on macOS, KVM on Linux, or Windows Hypervisor Platform on Windows. Ensure virtualization is enabled.
- A supported host OS. smolvm is cross-platform across macOS, Linux, and Windows. Note that the Vulkan GPU path is currently unavailable on native Windows.
- An OCI image to boot. smolvm boots OCI-format images (the same standard Docker uses) pulled from Docker Hub, GHCR, or another OCI registry. Docker is not needed to pull or run them.
- The smolvm CLI installed. Installing
smolvmis enough for local CLI use. ThesmolSDK is a control surface for embedding VM management in apps and agents, not a prerequisite. - A rough resource budget. Defaults are 4 vCPUs and 8 GiB RAM per machine, with elastic memory via virtio balloon, so plan capacity.
Step-by-step
1. Install smolvm and verify the hypervisor backend
Install the smolvm CLI for your platform and confirm it detects the right backend: Hypervisor.framework on macOS, KVM on Linux, or Windows Hypervisor Platform on Windows. If detection fails, fix virtualization support first; everything else depends on it.
2. Boot your first microVM from an OCI image
Pick an OCI image from Docker Hub, GHCR, or your own registry and boot it as a microVM. smolvm pulls the image and boots it as a full VM with its own guest kernel. Defaults apply automatically, and you can override resources per machine.
3. Decide your network posture before the first untrusted run
The defaults differ by location, so decide your posture before the first untrusted run:
- Locally, networking is off by default. An untrusted workload cannot phone home unless you explicitly allow it, and you can restrict egress to an allowlist.
- On smol cloud, outbound access is open by default. Set
network.modetoblockedorallowCidrsto restrict it. Never assume the local default carries over.
Start with networking off and open only what the workload genuinely needs.
4. Declare the environment in a Smolfile
A Smolfile is a TOML file that declares a whole local VM in one checked-in artifact: image, resources, network policy, mounts, ports, and setup commands. Commit it so every teammate and CI runner gets the identical environment with one command. Remember the scope: the Smolfile configures local machines only.
5. Keep state where you want it
Local VMs are persistent: packages you install and state you create survive stop and start, making smolvm a good fit for long-lived development environments. The same is true on smol cloud, where a machine keeps its filesystem across stop and start, but deleting a machine removes it, so export any data you need first (see lifecycle, storage, and networking).
6. Package the environment for reuse
Once an environment is warm and correct, pack it into a self-contained .smolmachine file. It boots in under 200 ms on a host with the same architecture (arm64 or x86_64), with no install step or runtime downloads. This is how you hand a ready-to-run sandbox to a teammate or fan out identical environments for parallel runs. The packs and .smolmachine docs cover the artifact format.
7. Fan out with fork/branch when you need parallelism
For RL rollouts or many parallel agent tasks, use fork/branch: a copy-on-write live fork of a running VM. Keep one warm environment and branch it as needed instead of cold-booting each worker.
8. Move CPU workloads to smol cloud when you outgrow laptops
When you need machines that outlive laptops, create cloud machines from an OCI image or a .smolmachine reference through the Cloud API. Cloud clients do not need a local hypervisor, and a local machine and a cloud machine can share an image or a compatible packaged environment while remaining separate runtime instances. GPU workloads stay local: smol cloud has no GPU machines, so CUDA and Vulkan work runs on smolvm on your own host.
Common pitfalls
- Assuming cloud networking matches local networking. Locally, networking is off by default. On smol cloud, outbound access is open unless you set
network.modetoblockedorallowCidrs. Check it per environment. - Treating
.smolmachinefiles as universally portable. They boot only on a host with the same architecture (arm64 or x86_64). Build per architecture you deploy to. - Expecting one Smolfile to configure the cloud. The Smolfile drives local machines. Cloud machines come from an OCI image or a
.smolmachinereference. - Assuming GPU passthrough. smolvm does not pass a GPU through to the guest. CUDA works by API remoting (no NVIDIA driver or
/dev/nvidia*in the guest), and Vulkan runs through a paravirtualized GPU. See the GPU concepts doc. - Deleting a cloud machine to "pause" it. Stop and start preserves the filesystem; deletion removes it. Export first.
- Expecting checkpoints to capture CUDA state. A
.smolcheckpointcaptures a running machine, but not CUDA state. Prepared CUDA state is reused through a live fork on the same host. - Skipping the network policy for untrusted code. The VM boundary limits direct host access, but any host directory, network access, or forwarded credential you deliberately grant is available to the workload. Grant deliberately.
Frequently Asked Questions
Do I need Docker installed to use smolvm? No. smolvm runs isolated Linux microVMs with no Docker daemon required. It consumes OCI-format images, the same standard Docker uses, pulled from Docker Hub, GHCR, or other registries, but nothing in the runtime path depends on a host daemon.
What hypervisor does it use, and is that a supported path? Yes. smolvm uses libkrun as the VMM with a libkrunfw guest kernel, backed by Hypervisor.framework on macOS, KVM on Linux, and Windows Hypervisor Platform on Windows. These are the platforms. own virtualization interfaces.
How fast do machines start?
Sub-second. A pre-baked machine cold-starts in under 200 ms, and a packed .smolmachine boots with no install step or runtime downloads on a host with the same architecture (arm64 or x86_64).
Can I run GPU workloads like CUDA training inside a machine? Yes, locally. CUDA runs through API remoting: your NVIDIA GPU and host driver stay on the host, and lightweight shims forward CUDA/NVML calls to a host daemon that owns the GPU. Vulkan runs through a paravirtualized GPU. There is no GPU passthrough, and smol cloud has no GPU machines, so GPU work stays on your own host.
Conclusion
Running isolated Linux environments without a host Docker daemon is not a workaround; it is a better default for teams that handle untrusted code, AI agents, or multi-tenant CI work. The hypervisor-backed microVM path gives every workload its own kernel, starts in under a second, and packages into reusable artifacts. Install smolvm, declare your environment in a Smolfile, lock down networking before the first untrusted run, and move CPU workloads to smol cloud when laptops are not enough. Start with the Smol Machines docs and get your first sandbox running today.
Related Articles
- MicroVM Runtimes for Parallel Agent Evaluation: Why Teams Choose smolvm Over a Shared Container Runtime
- 4 Ways Teams Isolate Each Large-Scale Agent Evaluation Rollout in Its Own Disposable MicroVM
- Isolated, Pack-Based Linux MicroVMs for Reproducible Agent Evaluation: What ML Infrastructure Teams Should Use