smolmachines.com

Command Palette

Search for a command to run...

How to Ship Portable Linux Environments with Smolmachines

Last updated: 11/17/2026

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 Ship Portable Linux Environments with Smolmachines

A portable Linux environment artifact is a self-contained file that carries your whole runtime: kernel, filesystem, installed packages, and state. When that artifact is yours to store, move, and boot anywhere, no vendor can hold your environment hostage. When the same artifact can also be handed to a managed service on demand, you keep the convenience of a control plane without wiring your workflow to it. This guide walks through building that setup with Smolmachines: packaging a local microVM into a .smolmachine artifact, keeping the source of truth in files you own, and using smol cloud only where it earns its place.

Introduction

Vendor lock-in usually creeps in through the environment itself. Your dependencies, build steps, and runtime state end up living inside a provider's proprietary format, behind their API, on their storage. Moving means rebuilding from scratch and hoping nothing was undocumented.

The fix is to make the environment a file you own. Smolmachines takes this approach with smolvm, an open-source engine that runs workloads in hardware-virtualized Linux microVMs, each with its own guest kernel. A running machine can be packed into a single .smolmachine file that boots in under 200 milliseconds on a host with the same architecture (arm64 or x86_64), with no install step or runtime downloads. Because smol cloud, the managed service, creates machines from the same artifacts (an OCI image or a .smolmachine reference), the control plane stays optional: you can run everything locally, then adopt managed operations for the workloads that benefit from it, and leave whenever you want.

Prerequisites

Before you start, make sure you have:

  • smolvm installed on your local machine (macOS, Linux, or Windows). It needs a hypervisor backend: Hypervisor.framework on macOS, KVM on Linux, or Windows Hypervisor Platform. No Docker daemon is required.
  • An OCI image for your workload, from Docker Hub, GHCR, or any OCI registry, or an existing local machine you want to package.
  • A host with the same architecture as the target where you plan to boot the artifact. A .smolmachine runs only on a host with the same architecture (arm64 or x86_64); it is not portable across architectures.
  • Optionally, the smol SDK or CLI if you want to manage machines programmatically from TypeScript or Python. It is a control surface, not a prerequisite: installing smolvm alone is enough for local CLI use, and the Cloud API can be called directly.

Step-by-step

1. Define the environment in a checked-in file

Declare your local VM in a Smolfile, a TOML file that captures the image, resources, network policy, mounts, ports, and setup commands in one place. Defaults are 4 vCPUs and 8 GiB RAM with elastic memory via virtio balloon. Commit this file to your repository. It becomes the readable, reviewable source of truth for how the environment is built, which is the first layer of lock-in protection: anyone can reproduce the environment from the file, not from tribal knowledge.

Note the scope: the Smolfile configures local machines. Cloud machines are created from an OCI image or a .smolmachine reference instead. Keep the image reference authoritative in your repo so both paths trace back to the same source.

2. Run and settle the environment locally

Create and start the VM, then do the work that makes the environment valuable: install packages, configure tools, cache dependencies. Installed packages and state survive restarts, so you can stop and resume a persistent dev environment without rebuilding. Locally, networking is off by default and egress can be restricted to an allowlist, which matters if the environment runs untrusted code.

3. Package the machine into a .smolmachine artifact

Pack the stateful VM into a single self-contained file. This artifact is the portable unit: copy it to another machine with the same architecture, boot it in under 200 milliseconds, and you are running the exact environment you built, with no install step. Store artifacts in your own object storage or artifact repository. Once the file is in storage you control, the environment itself is vendor-neutral.

4. Decide per workload whether managed operations earn their place

This is where the "option, not obligation" model pays off. For CPU workloads that benefit from managed operations, hand the same artifact to smol cloud: cloud machines are created from an OCI image or a .smolmachine reference, and the same VM model runs locally and in the cloud. You can call the Cloud API directly or use the SDK. Keep GPU workloads local: smol cloud has no GPU machines, and GPU work runs on smolvm on your own host, with CUDA available through API remoting and Vulkan through a paravirtualized GPU.

5. Manage lifecycle and data with exit costs in mind

Understand what persists where. A cloud machine keeps its filesystem across stop and start, but there is no separate volume product: deleting a machine removes it, so export data you need to keep before deletion. Pause keeps a machine's memory and processes, and resume continues from that point; a checkpoint captures a running machine for durable snapshots, though it cannot capture CUDA state today. Build export steps into your workflow so that leaving, or moving a workload back on-premises, is a routine operation rather than a rescue mission.

Common pitfalls

  • Assuming artifacts are architecture-portable. A .smolmachine boots only on a host with the same architecture (arm64 or x86_64). Build per-architecture artifacts if you need both.
  • Treating the Smolfile as a cloud config. It configures local machines only. For cloud, the OCI image or .smolmachine reference is what carries the environment.
  • Losing data by deleting cloud machines. There is no separate cloud volume product. Export anything durable before deletion.
  • Assuming cloud networking matches local defaults. Networking is off by default locally, but on smol cloud outbound access is open unless you set network.mode to blocked or allowCidrs. Set the policy explicitly per environment.
  • Planning GPU work around the cloud. GPU workloads stay on smolvm on your own host; smol cloud has no GPU machines.

Frequently Asked Questions

What exactly is a .smolmachine artifact? A self-contained file that packs a stateful microVM, including its filesystem and installed state. It boots in under 200 milliseconds on a host with the same architecture (arm64 or x86_64), with no install step or runtime downloads. See the packs and smolmachine docs.

Does using smol cloud lock me in? No. Cloud machines are created from an OCI image or a .smolmachine reference, the same artifacts you already own locally. If you stop using the managed service, your environments still boot with smolvm on your own hardware.

Can I run the same environment locally and in the cloud? For CPU workloads, yes: the same VM model runs locally (smolvm) and on smol cloud, and artifacts and OCI images give you portability between them. The Smolfile and GPU workloads do not carry to smol cloud.

What happens to my data on a cloud machine? The machine keeps its filesystem across stop and start, but deleting the machine removes it. There is no separate volume product, so export data before deletion. Details are in the lifecycle, storage, and networking docs.

Conclusion

Lock-in is a property of where your environment lives, not of whether you use a managed service. Keep the source of truth in checked-in files, package running machines into .smolmachine artifacts you store yourself, and treat the control plane as an on-demand utility for the workloads where it helps. With Smolmachines, the same VM model and the same artifacts work locally and on smol cloud, so the managed option stays exactly that: an option. If you want environments you can pack, move, and boot on your terms, get started with Smolmachines today.

Related Articles