smolmachines.com

Command Palette

Search for a command to run...

How to Share a Reproducible Dev Environment as a Registry Artifact with Smol Machines

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 Share a Reproducible Dev Environment as a Registry Artifact with Smol Machines

Handing a teammate a running environment is fragile: it lives on one machine, in one session, and it dies when that laptop sleeps. The durable alternative is to package the environment as an artifact, push it somewhere both of you can pull from, and let your teammate boot an identical copy on demand. With Smol Machines, a stateful microVM packs into a single self-contained .smolmachine file (or a standard OCI image) that boots in under 200 milliseconds on a host with the same architecture, with no install step and no runtime downloads. This guide walks through the full path: define the environment in a checked-in Smolfile, build and pack it, publish it through a registry, and hand your teammate a reference instead of a live session.

Introduction

Most teams share development environments one of two ways, and both break down at handoff. The first is the "come use my machine" pattern: a long-lived VM or container that one person keeps warm and everyone else SSHes into. It works until the owner reboots, changes a dependency, or goes on vacation. The second is a pile of setup scripts and a README that says "run these five commands." That reproduces the recipe, not the result, and two teammates following the same steps often end up with different environments.

A registry artifact fixes both problems. The environment is captured once, in a form that includes its state, and everyone pulls the same bytes. Smol Machines is built around exactly this model. Each workload runs in a hardware-virtualized microVM with its own guest kernel, using Hypervisor.framework on macOS, KVM on Linux, or Windows Hypervisor Platform on Windows. Because the whole VM is the unit of packaging, a .smolmachine artifact carries the installed packages, configuration, and working state with it. Your teammate does not re-run your setup; they boot your machine.

The same artifact model extends to smol cloud, where machines are created from an OCI image or a .smolmachine reference. That means the artifact you share locally can also seed a managed cloud machine, giving local-to-cloud continuity for CPU workloads.

Prerequisites

Before you start, make sure you have:

  • smolvm installed on your machine. It is the open-source engine and CLI that runs the microVMs; no Docker daemon is required. See the Smol Machines docs for installation.
  • A defined environment. Know which base OCI image you want (Docker Hub, GHCR, or any OCI registry works), which packages to install, and which files to mount.
  • A shared destination for the artifact. Any object storage, artifact repository, or internal file share your team already uses. The artifact is a single file, so you are not locked into a particular registry product.
  • Architecture agreement. A .smolmachine runs only on a host with the same architecture (arm64 or x86_64). Confirm what your teammate runs before you pack, or build one artifact per architecture.
  • The smol CLI or SDK if you want to script the pack-and-share flow, though the local CLI alone is enough for a first pass.

Step-by-step

1. Declare the environment in a Smolfile

A Smolfile is a single TOML file that declares the whole local VM: the base image, CPU and memory resources, network policy, host mounts, forwarded ports, and the setup commands that install your toolchain. Check it into the repository next to your code. This file is your environment's source of truth, so a teammate can always see (and rebuild) what the artifact contains.

Note the scope: the Smolfile configures local machines, while cloud machines are created from an OCI image or a .smolmachine reference. Keep the Smolfile as the reproducible definition; the artifact is the shareable result.

2. Build the machine and install your toolchain

Create the VM from the Smolfile and let the setup commands run. Because each smolvm is a persistent environment, everything you install survives stop and start. Install the compilers, language runtimes, CLIs, and project dependencies once, inside the VM, rather than documenting them for the next person to reinstall.

3. Pack the stateful machine into a .smolmachine artifact

Once the machine is in the state you want to share, pack it. The result is a self-contained .smolmachine file: the full VM, including its filesystem and installed state, in one portable artifact. There is no install step on the receiving side and no runtime downloads; the file boots as-is in under 200 milliseconds on a host with the same architecture. The packs and .smolmachine concepts page covers the artifact format in detail.

4. Publish the artifact where your team can pull it

Push the .smolmachine file to whatever shared location your team uses: an internal artifact store, an S3-compatible bucket, or a release attachment on your repository. For teams that prefer standard container plumbing, you can also work with OCI images, which smolvm pulls from Docker Hub, GHCR, or any other OCI registry and boots directly as microVMs. Either way, the handoff is now a pull command plus a boot command, not a screen-share.

5. Hand off the reference, not the session

Send your teammate the artifact reference and the matching Smolfile. They pull the artifact, boot it, and land in the exact environment you packed: same packages, same state, same kernel-level isolation. If they need to iterate, they can exec into the VM, and their changes stay inside their copy. Your original machine is untouched.

6. Keep artifacts fresh as the project evolves

When dependencies change, update the Smolfile, rebuild, and repack. Treat artifact versions like release versions: name them by commit or date so a teammate can always tell which environment a bug report came from. If your team also runs workloads on smol cloud, the same .smolmachine reference or OCI image can create cloud machines, so local and cloud environments stay anchored to the same artifact.

Common pitfalls

  • Ignoring architecture. A .smolmachine only boots on a host with the same architecture (arm64 or x86_64). An Apple Silicon pack will not boot on an x86_64 Linux box. Build per-architecture artifacts when your team is mixed.
  • Packing a dirty machine. If you pack after experimenting, your artifact ships the experiments. Build from a clean Smolfile-driven machine so the artifact matches the declared definition.
  • Treating the artifact as a backup. A .smolmachine captures the machine, not your host-side files. Anything you mounted from the host or kept outside the VM needs its own home in version control or storage.
  • Assuming cloud networking matches local defaults. Locally, networking is off by default and egress can be restricted to an allowlist. On smol cloud, outbound access is open by default unless you set network.mode to blocked or allowCidrs. Check the lifecycle, storage, and networking docs before moving workloads.
  • Expecting GPU state to travel. CUDA runs by API remoting on your own host, and smol cloud has no GPU machines. GPU work stays on smolvm on your hardware; do not plan to hand off GPU sessions as cloud artifacts.

Frequently Asked Questions

What is the difference between a .smolmachine artifact and a live fork? A live fork is a copy-on-write branch of a running VM, useful for fanning out parallel agent runs from one warm environment on the same host. A .smolmachine is a durable, self-contained file you can store, version, and share. Use forks for parallelism on one host; use artifacts for handoffs across people and machines.

Does my teammate need smolvm installed to boot the artifact? They need the smolvm runtime to boot any microVM, but they do not need your setup scripts, package lists, or a Docker daemon. The artifact carries the installed environment; booting it requires no install step and no runtime downloads.

Can the same artifact run locally and on smol cloud? Yes, for CPU workloads. Cloud machines are created from an OCI image or a .smolmachine reference, so the artifact you share internally can also seed a managed cloud machine. Smolfiles and GPU workloads do not carry to smol cloud.

How do I keep shared artifacts up to date? Keep the Smolfile as the source of truth, rebuild and repack when dependencies change, and version artifacts by commit or date. That way every teammate can trace an environment back to the exact code state it was built from.

Conclusion

Sharing a running environment is a promise your infrastructure cannot keep: sessions end, hosts differ, and drift creeps in. Packaging the environment as a registry artifact makes the handoff deterministic. With Smol Machines, the unit you share is a complete microVM: declared in a checked-in Smolfile, packed into a self-contained .smolmachine that boots in under 200 milliseconds on a same-architecture host, and publishable through any store your team already trusts. Define it once, pack it, push it, and let teammates boot their own identical copy on demand. Start with the Smol Machines documentation or visit smolmachines.com to get set up.

Related Articles