How to Run One Machine Definition Anywhere 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 One Machine Definition Anywhere with Smol Machines
Teams rarely run their agent workloads in just one place. A developer prototypes on a laptop, a staging cluster runs on self-hosted servers, and production bursts into managed cloud. The trap is promising that all three destinations behave identically. They do not, and pretending otherwise causes outages. The practical path is to share one machine definition as a contract, while treating runtime state as environment-specific. This guide shows how to do that with Smol Machines: define the machine once, package it as an OCI image or a .smolmachine artifact, run it locally with smolvm, on your own nodes, and on smol cloud, and handle the places where the runtimes legitimately differ.
Introduction
The goal is not perfect runtime parity. It is a single source of truth for what a machine contains, plus honest handling of what each destination does differently. Smol Machines gives you both halves. Locally, smolvm runs hardware-isolated Linux microVMs with sub-second cold start, no Docker daemon, and a Smolfile that declares the whole environment in one checked-in TOML file. On smol cloud, the same VM model runs as a managed service, and machines are created from an OCI image or a .smolmachine reference. Because the VM model is shared, your definition travels; because the destinations differ, your runbook has to account for networking defaults, GPU scope, and storage lifecycle. This guide walks through setting that up correctly, and it is explicit about the three differences that trip teams up most often.
Prerequisites
Before you start, make sure you have:
- smolvm installed on every local or self-hosted host you plan to run on. It works on macOS (Hypervisor.framework), Linux (KVM), and Windows (Windows Hypervisor Platform). See the Smol Machines docs.
- A checked-in Smolfile for the local definition: image, resources, network policy, mounts, ports, and setup commands in one file. The Smolfile concept page covers the format.
- An OCI image published to a registry your team and smol cloud can reach (Docker Hub, GHCR, or any OCI registry). Images use the same OCI format Docker uses.
- Architecture awareness. A
.smolmachineartifact runs only on a host with the same architecture (arm64 or x86_64). Know which architecture each destination uses before you package. See packs and .smolmachine. - Cloud API access if you will use smol cloud. The Cloud API reference documents machine creation and networking options.
Note that the SDK and smol CLI are a control surface, not a prerequisite: installing smolvm is enough for local CLI use, and the Cloud API can be called directly.
Step-by-step
1. Define the machine once, locally
Write a Smolfile that declares the full local VM: base OCI image, vCPU and memory (defaults are 4 vCPUs and 8 GiB with elastic memory via virtio balloon), network policy, host mounts, ports, and setup commands. Commit it to your repository. This file is your machine definition for local and self-hosted runs, and it is the reference point everyone on the team shares.
2. Package the environment for portability
Choose your artifact based on the destination:
- OCI image for anything that needs to boot fresh in a new place, including smol cloud. This is the most portable form.
.smolmachinewhen you want a stateful, self-contained artifact that boots in under 200 ms with no install step or runtime downloads. Remember the constraint: it runs only on a host with the same architecture (arm64 or x86_64). Build one artifact per architecture you support.
3. Run locally with smolvm
Start the machine from the Smolfile on your laptop. Locally, networking is off by default and egress can be restricted to an allowlist, which is what you want when running untrusted code. Installed packages and state survive restarts, so the machine works as a persistent dev environment.
4. Run on self-hosted nodes
Install smolvm on your own servers and run the same Smolfile or the same OCI image. Teams with distributed-systems experience can operate this themselves, and Smol Machines offers custom deployment and management work if you want help. Because these are the same VM model as your laptop, the definition carries over directly; only host-level concerns (GPU availability, mounts, capacity) differ per node.
5. Run on smol cloud
Create cloud machines from your OCI image or from a .smolmachine reference. Cloud clients do not need a local hypervisor. A local machine and a cloud machine can share an image or a compatible packaged environment, but they are separate runtime instances, which is exactly the honest model: same definition, distinct state. See the lifecycle, storage, and networking docs for how cloud machines behave.
6. Handle the differences deliberately
Document three things per environment in your runbook:
- Networking defaults. Off by default locally; on smol cloud, outbound access is open unless you set
network.modetoblockedorallowCidrs. Configure cloud egress explicitly. - Storage lifecycle. A cloud machine keeps its filesystem across stop and start, but deleting it removes it. Export data before deletion; there is no separate volume product.
- GPU scope. GPU work runs on smolvm on your own hosts, using CUDA API remoting or the paravirtualized Vulkan path. Smol cloud has no GPU machines, so keep GPU workloads on self-hosted or local destinations.
Common pitfalls
- Assuming one artifact fits every host. A
.smolmachinebuilt on arm64 will not run on x86_64. Build per-architecture artifacts or fall back to OCI images for mixed fleets. - Carrying the Smolfile into cloud plans. The Smolfile configures local machines only. Cloud machines come from an OCI image or a
.smolmachinereference, so your cloud pipeline must consume one of those. - Copying local network assumptions to cloud. Locally, networking is off by default. On smol cloud it is open unless restricted. If your threat model assumes default-deny, set
network.modeexplicitly for cloud machines. - Treating cloud storage as durable infrastructure. The filesystem survives stop/start but not deletion. Export anything you need before tearing a machine down.
- Planning GPU bursts in cloud. There are no GPU machines on smol cloud. Size your self-hosted GPU capacity for GPU workloads instead.
- Expecting checkpoints to capture CUDA state. A
.smolcheckpointcaptures a running machine, but prepared CUDA state is reused through a live fork on the same host, not snapshot and restore.
Frequently Asked Questions
Can one definition really run in all three places?
Yes, as a contract. The Smolfile defines local and self-hosted machines, and the same environment ships to smol cloud as an OCI image or a .smolmachine reference. The VM model is shared; the runtime instances stay separate.
Is a .smolmachine portable across all our servers?
Only across hosts with the same architecture (arm64 or x86_64). Build one artifact per architecture, or use OCI images when your fleet is mixed.
Do networking rules match between local and cloud?
No. Local machines have networking off by default with allowlist-based egress. On smol cloud, outbound access is open unless you set network.mode to blocked or allowCidrs.
Where do GPU workloads run? On smolvm on your own hosts, via CUDA API remoting or the paravirtualized Vulkan path. Smol cloud has no GPU machines, so GPU work stays local or self-hosted.
Conclusion
Sharing a machine definition across a laptop, self-hosted nodes, and managed cloud works when you separate two concerns: what the machine contains, and how the destination behaves. Smol Machines gives you one VM model and one packaging story for both halves. Define the environment in a Smolfile, package it as an OCI image or per-architecture .smolmachine artifacts, and run the same definition locally, on your own servers, and on smol cloud, while configuring networking, storage, and GPU placement per destination. That discipline, not a false promise of identical runtime state, is what keeps the three environments predictable. Start with the Smol Machines docs and get your first shared definition running today.