This FAQ clarifies product boundaries, technical tradeoffs, and common misunderstandings. See the documentation for setup and implementation details.
smol SDK, and how do they fit together?smolvm is the open-source engine and CLI for running isolated Linux virtual machines locally. smol cloud is the managed service for running smolvm-based workloads in the cloud. smol is the open SDK and CLI for creating and managing workloads locally or on smol cloud. It gives applications and coding agents one interface across both environments.
Use smolvm when the workload runs on your own computer or infrastructure and you want to operate it yourself. It is free, portable, and a good fit for local development, coding agents, and isolated workloads.
Use smol cloud when you need managed, persistent cloud VMs without operating the underlying fleet. It is built for workloads such as deployed agents and long-running processes.
Teams with distributed-systems experience can also run smolvm on their own servers. smol machines offers custom deployment and management work for designated locations or specialized requirements.
Yes. smolvm and smol cloud use the same VM model, so a workload can be developed locally and then deployed with the same configuration or packaged .smolmachine artifact where supported. This does not mean a running local VM can always be moved live into smol cloud; live migration and snapshots are separate capabilities.
smolvm runs workloads that need a real Linux kernel and a VM boundary without the long startup time and operational weight often associated with traditional VMs. It is designed for isolated agent execution, untrusted code, portable development environments, and workloads that benefit from fast startup or VM fork.
smolvm can run most Linux workloads that need isolation or controlled access. Common uses include coding-agent sandboxes, untrusted code execution, persistent development environments, CI tasks, headless browsers, and local CUDA workloads.
The smolvm CLI manages local lifecycle operations such as creating, starting, stopping, executing commands in, packing, and forking VMs. The smol SDK and CLI let applications or coding agents manage local smolvms and smol cloud VMs programmatically.
smolvm or smol?Start with smolvm if you want to run a workload locally through the CLI. Start with smol if you are embedding VM management in a TypeScript or Python application, or want one API for local and cloud workloads. Use smol cloud when you need managed cloud infrastructure.
smol and smolvm-sdk?smol is the current open SDK and CLI. Its smolmachines packages embed the engine for local use and can also connect to smol cloud.
smolvm-sdk is the older, thin REST client for a local smolvm serve instance. It remains useful for integrations that already use that API, while smol is the recommended starting point for new embedded applications.
Docker packages and runs containers that share the host kernel. smolvm can start the same OCI images, but each workload runs in its own hardware-virtualized VM with its own guest kernel. smolvm does not need a Docker daemon on the host.
Docker and smolvm can also be used together: Docker can build an OCI image that smolvm runs, and Docker can run inside a smolvm when a workload needs it.
Containers isolate processes while sharing the host kernel. A virtual machine has a guest kernel and a hypervisor boundary. That distinction matters when an agent or untrusted workload needs stronger separation from the host, or when the workload expects to control kernel features such as cgroups, mounts, and networking.
smolvm is a microVM runtime designed to keep this VM boundary while retaining container-like workflows and fast startup.
Cold-start time measures how quickly a VM boots. Time-to-ready measures the full wait before useful work can begin: boot time plus image pulls, dependency installation, and environment provisioning.
For an agent or developer, time-to-ready is usually the more useful metric. Prebuilt .smolmachine artifacts and registry environments can avoid repeating setup work, which reduces the total wait.
smolvm is a VM runtime. It can pull and boot OCI images, the open image format also used by Docker, as virtual machines. It can also package a stateful VM environment into a .smolmachine artifact for reuse on a compatible host.
No. smolvm can pull OCI images from Docker Hub, GHCR, or another OCI registry without a Docker daemon. You may still use Docker or another container tool to build or export an image before running it with smolvm.
Yes. Docker inside a smolvm is useful for workloads that expect a Docker daemon, such as some agent tools and test frameworks. Docker storage needs to live on the VM’s ext4 storage disk because Docker’s overlay2 storage driver cannot run on the VM root filesystem’s overlay.
smolvm also supports two Kubernetes patterns: running a complete k3d or k3s cluster inside one smolvm, or using its containerd shim to run Kubernetes pods as smolvms. These solve different problems and have separate setup paths.
Each local smolvm runs behind a hypervisor boundary with its own guest kernel. Networking is disabled by default, and mounts, forwarded ports, SSH-agent access, and other capabilities are explicit choices.
The VM boundary limits direct host access, but it is not a substitute for careful host security. A workload receives any host directory, network access, or forwarded credential capability that you deliberately give it.
Networking is disabled by default so a workload cannot reach the internet or other network services unless you allow it. Enable networking when the VM needs to pull an image, download dependencies, call an API, upload a result, or serve traffic. Where possible, use the egress allowlist to restrict access to the hosts or networks the workload actually needs.
Treat a smolvm like any other environment that runs your code. Secret injection places plaintext values inside the guest, so code in that VM can read them. SSH-agent forwarding keeps private key material in the host agent, but the guest can request signatures while the forwarded socket is available.
Only grant a workload the credentials and host capabilities it needs, and avoid mounting sensitive host paths into untrusted workloads.
Both lifecycle modes are available. smolvm machine run creates an ephemeral VM that is cleaned up when the command exits. machine create, start, stop, and exec manage a persistent local VM whose installed packages and state survive restarts.
smol cloud is designed for persistent cloud VMs. Choose the lifecycle that matches whether the workload is a one-off task, a reusable environment, or a long-running service.
.smolmachine file, and when should I use one?A .smolmachine file is a portable, self-contained package of a stateful VM environment. It pre-bakes the runtime and dependencies so the workload can start without re-pulling an image or repeating installation.
Use one when you want a reproducible environment, faster time-to-ready, or an artifact that can run on compatible local or cloud infrastructure. Host architecture still needs to match the artifact.
A VM fork creates a new smolvm from the current state of an existing one. The fork uses copy-on-write memory and keeps running processes alive, so it is much faster than rebuilding the same environment from scratch.
Fork is useful for testing divergent changes from a known state, running many agent tasks from one prepared environment, and creating copies of a warm, model-loaded inference service.
smolvm has two GPU paths:
Use the Vulkan path when the workload needs accelerated graphics. Use CUDA remoting when the workload uses NVIDIA’s CUDA ecosystem. Host and platform requirements differ for each path; CUDA requires an NVIDIA GPU and host driver, while Vulkan requires a supported Vulkan host stack.
The guest contains lightweight compatibility shims instead of an NVIDIA driver or /dev/nvidia* devices. These shims intercept CUDA and NVML calls, forward them over vsock to a host daemon that owns the real GPU and driver, and return the results to the workload.
This lets an unmodified CUDA application see a CUDA device while keeping the driver and physical device outside the guest.
No. GPU passthrough assigns a physical GPU and its driver stack to one VM. smolvm uses CUDA API remoting: multiple smolvms connect to a host daemon that owns one GPU context.
This allows GPU sharing and warm GPU forks, but it is not a hardware-partitioned, multi-tenant GPU boundary. Workloads on the same GPU can contend for VRAM and scheduling.
CUDA remoting adds an RPC hop to each CUDA call, so workloads with many small latency-sensitive calls can see overhead. The CUDA API surface must also be implemented and kept current, so an unsupported call can fail even when it would work with direct passthrough.
It is NVIDIA-only and still requires an NVIDIA GPU and driver on the host. The VM isolates CPU, memory, and filesystem state, while GPU sharing remains process-level rather than hardware partitioning.
Yes. CUDA remoting supports compatible local NVIDIA workloads for model training, fine-tuning, and inference. smolvm can also expose Vulkan through virtio-gpu and Venus for headless browsers and accelerated WebGL workloads.
Check the host and guest requirements for the path you need. GPU support is platform-specific; for example, the current Vulkan path is unavailable on native Windows.
smolvm runs Linux guests on:
Guest architecture must match the host architecture. Intel macOS support is listed as untested in the current documentation.
Yes. smolvm runs directly on native Windows through smolvm.exe when WHP is enabled. This is the preferred Windows path.
WSL2 is an alternative on Windows 11 when nested virtualization and KVM are available. WSL2 on Windows 10 cannot provide the nested KVM path smolvm needs. Native Windows currently does not support Vulkan GPU acceleration, VM fork, or snapshots.
Yes. smolvm is library-first: the Rust crate is the native engine, and the smol SDK exposes embedded local smolvm support through Node and Python bindings. Applications can also use smol to manage smol cloud workloads.
The older smolvm-sdk is a REST client for a local smolvm serve process. It is useful for existing local-server integrations, but new embedded applications should generally start with smol.