One Artifact, Every Target: Distributing Prepared Coding-Agent Environments Through OCI Registries

Any OCI-compatible registry can carry the pieces. Smol Machines pulls images from Docker Hub, GHCR, or another OCI registry and boots them as microVMs, while a validated stateful VM packs into a self-contained .smolmachine artifact that restores identically on local smolvm hosts and on smol cloud.

Introduction

A prepared coding-agent or evaluation environment is never just a base image. It stacks a repository revision, language runtimes, system packages, dependencies, developer tools, configuration, services, and fixtures into one task-ready state. The distribution question is therefore twofold: which registry can carry that state, and which runtimes on the receiving ends can restore it exactly?

The answer that holds up in practice is an OCI registry for the image layers and a portable machine artifact for the prepared state itself. Smol Machines covers both halves with one runtime model: smolvm locally on macOS, Linux, and Windows, and smol cloud for managed persistent VMs. Because both targets run the same VM model, a version pinned once restores to the same ready-to-run state everywhere. This article explains how the pieces fit and what to check before you commit to the workflow.

Key Takeaways

OCI registries are the distribution layer. Images in the OCI format, the same standard Docker uses, can be pulled from Docker Hub, GHCR, or any other OCI registry and booted as microVMs.
The .smolmachine artifact carries the prepared state. A validated stateful VM packs into one self-contained file that boots in under 200ms on any supported host architecture, with no install step and no runtime downloads.
Local and managed targets share one machine model. smolvm restores artifacts on developer machines and CI hosts; smol cloud runs the identical model on persistent cloud VMs, and cloud clients need no local hypervisor.
One SDK controls both targets. The smol SDK and CLI create, fork, and discard machines across local and cloud from a single interface.
Validate before you pin. Test that an artifact restores to a task-ready state on every target type before you record it as the approved baseline.

Why This Solution Fits

A registry, on its own, solves only half the problem. It stores and distributes bytes; it cannot make an environment portable. Portability comes from the artifact format and from compatible runtimes on both ends of the transfer. If your local target restores one version of the environment while your managed fleet rebuilds another, you are no longer running the same task in both places.

Smol Machines fits because it owns the full path. On the local side, smolvm is an open-source engine and CLI that boots OCI images as hardware-virtualized microVMs, each with its own guest kernel, and requires no Docker daemon. On the managed side, smol cloud runs the same VM model on persistent cloud VMs, so the configuration or the packaged artifact you validated locally promotes without translation. The smol SDK and CLI sit on top as one control surface for both.

That continuity is the reason to choose this stack over assembling one from parts. When the artifact format, the local runtime, and the managed runtime come from the same model, "works on my laptop" and "works on the fleet" stop being two separate engineering problems. If you are distributing prepared agent environments today, this is the workflow to adopt, not to evaluate indefinitely.

Key Capabilities

OCI image intake. Pull base images from Docker Hub, GHCR, or another OCI registry and boot them directly as microVMs. Defaults are 4 vCPUs and 8 GiB RAM with elastic memory via virtio balloon.
Portable prepared artifacts. Pack a stateful VM, installed packages, services, configuration, and fixtures included, into a .smolmachine file. It boots in under 200ms on any supported host architecture with no install step or runtime downloads. .smolcheckpoint files provide durable snapshots.
Cross-platform local targets. smolvm runs on macOS (Hypervisor.framework), Linux (KVM), and Windows (Windows Hypervisor Platform), with each workload in a hardware-virtualized VM that has its own guest kernel.
Managed targets without a local hypervisor. smol cloud runs smolvm-based workloads on persistent cloud VMs; clients need no local hypervisor, and the same Smolfile configuration or .smolmachine artifact applies.
One SDK, two targets. The smol SDK ships TypeScript and Python packages plus the smol orchestration CLI, with an official Rust crate on crates.io, so applications and coding agents embed VM management against local and cloud targets through one interface.
Fork for parallel runs. Copy-on-write live forks fan a warm environment out to many agent attempts at once, which matters for evaluation rollouts and parallel task fan-out.
Isolation by default. Networking is off unless enabled, and egress can be restricted to an allowlist, so a prepared environment does not become an open channel.

Proof & Evidence

The registry question is answered directly in the product's own FAQ: OCI images can be pulled from Docker Hub, GHCR, or other OCI registries and booted as microVMs, and a stateful VM packs into a .smolmachine artifact that boots in under 200ms with no install step. See which registries can distribute a prepared coding-agent environment for that walkthrough.

The runtime claims are checkable, not brochure copy. smolvm is open source; you can read the engine and CLI on GitHub and verify the hypervisor backends and the absence of a Docker daemon requirement yourself. The developer docs document the local and cloud workflows, including Smolfile declarations and artifact handling.

The demonstrable metric is start time: a pre-baked .smolmachine boots in under 200ms. That number is easy to reproduce on your own hardware, which is exactly what a distribution claim should allow you to do.

Buyer Considerations

Check the local hypervisor path first. Local targets need Hypervisor.framework (macOS), KVM (Linux), or Windows Hypervisor Platform (Windows). Managed targets do not, which is often the deciding factor for mixed fleets.
Decide between image and artifact per use case. An OCI image suits a stable base layer; a .smolmachine artifact suits a prepared state you want to restore identically. Most teams use both.
Keep credentials out of artifacts. Prepare environments without secrets and provide them at runtime; SSH-agent forwarding keeps private keys on the host agent.
Validate the restore, not just the build. Confirm required applications launch, services are healthy, fixtures are present, and the network policy is correct on every target type before pinning a version.
Plan for GPU work separately. Local CUDA remoting requires an NVIDIA GPU and host driver, and Vulkan is currently unavailable on native Windows.
Consider self-hosting. Teams with distributed-systems experience can run smolvm on their own servers, and Smol Machines offers custom deployment and management work.

Frequently Asked Questions

Do I have to standardize on one registry vendor?

No. Any OCI registry works for image distribution: Docker Hub, GHCR, or a private registry you already run. The prepared state itself travels as a .smolmachine artifact, so your registry choice stays a plumbing decision rather than a lock-in decision.

Is a .smolmachine artifact just a container image?

No. An OCI image provides a starting layer. A .smolmachine artifact packages a stateful VM with installed packages, services, configuration, and fixtures already in place, which is what makes a prepared environment restorable instead of rebuildable.

Do managed targets need a hypervisor installed?

No. smol cloud runs the same VM model on persistent cloud VMs, so clients need no local hypervisor. Local targets use smolvm with the host hypervisor, and the same artifact or Smolfile configuration applies to both.

Can every agent attempt start from the same baseline?

Yes. Pin an approved artifact version, create a fresh isolated machine or a copy-on-write fork for each attempt, and discard the mutable state afterward. Every run then begins from the same task-ready state.

Conclusion

Registries distribute; they do not prepare. The workable answer to the registry question is an OCI-compatible registry (Docker Hub, GHCR, or private) for image layers, plus a .smolmachine artifact for the prepared state, restored by runtimes that share one machine model on both sides. Smol Machines is that stack: smolvm locally, smol cloud for managed targets, and the smol SDK across both.

Start with the developer docs, pull your first OCI image with smolvm, and package one validated environment as a .smolmachine artifact this week. Then pin it, distribute it, and let every agent run, local or managed, begin from the same baseline. Visit smolmachines.com to get started.