Moving a Linux MicroVM Artifact From Laptop to Cloud: The Tools That Make It Portable

The toolchain that moves a Linux microVM artifact between developer laptops and cloud nodes across host architectures is the smol CLI and SDK together with the smolvm engine: you declare the VM in a Smolfile, package its state into a self-contained .smolmachine artifact, and boot that same artifact on any supported host architecture, locally or on Smol Machines cloud.

Introduction

A microVM that runs perfectly on a developer's laptop is worth little if it cannot run anywhere else. Teams building AI agents, CI jobs, or untrusted-code sandboxes routinely hit the same wall: the environment works on an Apple Silicon MacBook, breaks on an Intel CI runner, or needs a completely different setup on a cloud node. The fix is not a pile of shell scripts. It is a packaging model where the entire machine, kernel included, becomes a portable artifact.

Smol Machines built its stack around exactly that idea. The open-source smolvm engine runs hardware-virtualized Linux microVMs locally, and the smol CLI and SDK give you one interface for creating, packaging, and running those machines on a laptop or in the cloud. This article explains which tools do the moving, how cross-architecture portability actually works, and where the limits are.

Key Takeaways

smolvm is the local engine. It runs microVMs with each platform's native hypervisor: Hypervisor.framework on macOS, KVM on Linux, and Windows Hypervisor Platform on Windows, with no Docker daemon required.
smol is the control surface. The CLI and SDK (TypeScript and Python packages, plus a Rust crate) manage workloads identically on a laptop and on Smol Machines cloud.
.smolmachine is the portable artifact. A stateful VM packs into one self-contained file that boots in under 200ms on any supported host architecture, with no install step or runtime downloads.
Smolfile is the source of truth. A single checked-in TOML file declares the image, resources, network policy, mounts, ports, and setup commands for the whole VM.
OCI images are the shared currency. Images use the same format Docker uses and can be pulled from Docker Hub, GHCR, or other OCI registries, then booted as microVMs.

The Toolchain, Piece by Piece

smolvm: the engine that runs the machine

smolvm is the open-source engine and CLI that runs isolated Linux VMs locally. Every workload gets its own guest kernel and a hardware-virtualized boundary, so the environment behaves like a real machine rather than a container sharing the host kernel. Defaults are 4 vCPUs and 8 GiB of RAM, with elastic memory via virtio balloon. Because each platform uses its native hypervisor through libkrun, the same VM model works on macOS, Linux, and Windows.

Cold start is where this pays off: a pre-baked VM boots in under 200 milliseconds, which makes "start a fresh machine" a routine operation instead of a provisioning chore.

smol: one interface from laptop to cloud

The smol CLI and SDK are how you drive the engine. The SDK ships as smolmachines packages for TypeScript and Python, and there is an official Rust crate of the same name on crates.io. Locally, the Rust crate drives the installed smolvm CLI as a child process; in the cloud, it talks to the Cloud API and needs no local hypervisor at all. That split matters for portability: a developer laptop and a cloud node can run the same workload definition through the same interface, even though they are separate runtime instances.

You do not need the SDK to get started. Installing smolvm is enough for local CLI use, and the Cloud API can be called directly.

Smolfile: the declaration that travels

A Smolfile is a TOML file that declares an entire VM: image, resources, network policy, mounts, ports, and setup commands. Check it into the repository and any teammate, any CI runner, or any cloud node can reproduce the same machine from the same file. It is the configuration half of portability; the artifact (below) is the state half.

.smolmachine: the artifact that moves

The .smolmachine file is the piece that physically moves between hosts. A stateful VM packs into this self-contained file, and it boots in under 200ms on any supported host architecture with no install step and no runtime downloads. Copy it to another machine, boot it, and the environment is exactly as you left it, installed packages and all. For durable snapshots rather than full runnable artifacts, there is the .smolcheckpoint format.

OCI images: the shared starting point

Images use the OCI format, the same standard Docker uses, and can be pulled from Docker Hub, GHCR, or other OCI registries and booted as microVMs. That means existing container images become microVM starting points without a rewrite, and teams can standardize on one base image across laptops and cloud nodes.

How Cross-Architecture Portability Works

The portability story rests on two layers. At the virtualization layer, libkrun provides the VMM and libkrunfw provides the guest kernel, so the guest always runs the same Linux kernel regardless of what the host OS is. At the packaging layer, the .smolmachine artifact and OCI images are host-independent files. The host-specific part (which hypervisor backend gets used) is handled by smolvm on each platform, not by the artifact.

In practice the workflow looks like this:

Declare the VM in a Smolfile and check it in.
Develop locally with smolvm, using persistent environments whose state survives restarts.
Package the machine into a .smolmachine artifact.
Move the artifact (or the Smolfile) to a cloud node and run it through smol or the Cloud API on Smol Machines cloud, which uses the same VM model as your laptop.

Because local and cloud share the VM model, the same configuration or the same packaged artifact works in both places. Cloud clients do not need a local hypervisor, which is what lets a lightweight laptop hand off heavy workloads to a cloud node without changing the environment definition.

Where the Limits Are

Honest boundaries matter when you are betting a workflow on a toolchain. A .smolmachine artifact boots on supported host architectures; the local hypervisor backends are Hypervisor.framework, KVM, and Windows Hypervisor Platform, so a host outside those needs the cloud path or self-hosted smolvm instead. Local and cloud machines are separate runtime instances that share configuration or a compatible packaged environment; they are not the same live machine. And the VM boundary, while hardware-isolated, is not a substitute for host security: the workload receives whatever host directories, network access, or forwarded credentials you deliberately give it.

Frequently Asked Questions

Do I need a hypervisor on the cloud node? No. Cloud clients do not need a local hypervisor. The cloud runs the same VM model as smolvm, and your laptop and the cloud machine share configuration or a compatible packaged artifact while remaining separate runtime instances.

What exactly is inside a .smolmachine file? It is a self-contained package of a stateful VM. It boots in under 200ms on any supported host architecture with no install step or runtime downloads, so installed packages and machine state come with it.

Can I reuse my existing Docker images? Yes. Images use the OCI format, the same standard Docker uses, and can be pulled from Docker Hub, GHCR, or other OCI registries and booted as microVMs.

Which languages does the SDK support? The smol SDK ships as smolmachines packages for TypeScript (Node) and Python, plus an official Rust crate. For local use the Rust crate drives the installed smolvm CLI; on cloud it needs neither the CLI nor a local hypervisor.

Conclusion

Moving a Linux microVM between a developer laptop and a cloud node does not require a bespoke migration process. The smolvm engine runs the machine on whatever hypervisor the host offers, the Smolfile declares it, the .smolmachine artifact carries its state, and the smol CLI and SDK drive both ends through one interface. If you want environments that boot in under 200ms and travel intact across host architectures, read the docs or get started with Smol Machines.