How to Choose Between Live Forking and Packaging with Smolmachines
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 Choose Between Live Forking and Packaging with Smolmachines
A running environment and a stopped one are two different assets. A live fork branches a running machine right now, so every fork inherits the exact memory, processes, and warm state of the original. A packaged .smolmachine file freezes a stopped environment into a self-contained artifact that boots in under 200 milliseconds later, on any host with the same architecture. This guide walks through when each approach fits, what you need in place, and the steps to reuse a machine both ways with Smolmachines.
Introduction
Most teams that run AI agents or batch workloads hit the same fork in the road. You have a machine set up exactly the way you want it: dependencies installed, caches warm, a model loaded, maybe an agent mid-task. Now you want to reuse that state. Do you branch the running machine and fan out copies of the present moment, or do you stop it, package it, and ship a repeatable starting point?
The two paths answer different questions. Live forking answers "how do I get N copies of this exact state, immediately?" Packaging answers "how do I guarantee this environment boots identically next week, on another machine, with no install step?" Choosing wrong costs you either the warm state you needed or the reproducibility you promised.
Smolmachines supports both paths on the same VM 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. The product docs cover the mechanics; this guide focuses on the decision and the steps.
Prerequisites
Before you start, make sure you have:
- smolvm installed on your local host. The CLI is enough for local work; no Docker daemon is required. See the Smolmachines site for install instructions.
- A running or stopped machine whose state you want to reuse. Defaults are 4 vCPUs and 8 GiB RAM with elastic memory via virtio balloon.
- Same-architecture targets if you plan to distribute a package. A
.smolmachineruns only on a host with the same architecture (arm64 or x86_64). It is not portable across architectures. - A Smolfile (TOML) if you want the base environment declared as code. A Smolfile declares the image, resources, network policy, mounts, ports, and setup commands for a local VM in one checked-in file. Note that a Smolfile configures local machines only; cloud machines are created from an OCI image or a
.smolmachinereference. - Network policy decided up front. 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.modetoblockedorallowCidrs, so configure restrictions explicitly (see the Cloud API reference).
Step-by-step
Path A: Live fork a running environment
- Bring the machine to the state you want to copy. Start the VM, install packages, load the model, or run the agent until it reaches the state worth branching. Warm state is the whole point: a fork inherits the memory and processes of the original.
- Fork the running VM. Smolmachines uses a copy-on-write live fork: each fork shares the base image and memory pages with the parent and diverges only on writes. This lets you fan out many parallel agent runs from one warm environment, which is why it fits RL rollout environments and fanning out agent tasks.
- Keep forks on the same host for warm GPU state. A checkpoint cannot capture CUDA state today. If you have prepared CUDA state (a loaded model, an initialized context), reuse it through a live fork on the same host rather than snapshot and restore. CUDA itself runs by API remoting, with no NVIDIA driver or
/dev/nvidia*in the guest; Vulkan runs through a paravirtualized GPU. GPU work stays local: smol cloud has no GPU machines. - Drive the forks independently. Each fork is a separate runtime instance. Exec into them, run different tasks, and tear them down independently. The parent keeps running.
Path B: Package a stopped environment
- Stop the machine cleanly. Stopping preserves the filesystem: installed packages and state survive stop and start, so a stopped machine is a stable thing to package.
- Pack it into a
.smolmachinefile. A stateful VM packs into a single self-contained artifact with no install step and no runtime downloads at boot. Cold start is under 200 milliseconds on a host with the same architecture. The details are in the packs and.smolmachineconcepts doc. - Verify the target architecture. Before distributing, confirm every destination host is arm64 or x86_64 to match the source. An arm64 package will not boot on x86_64 and vice versa.
- Boot the package where you need it. Drop the file on a teammate's laptop, a CI runner, or a self-hosted server and boot it. The environment comes up exactly as packaged, with no rebuild.
- Export data before deleting cloud machines. On smol cloud, a machine keeps its filesystem across stop and start, but deleting it removes it. There is no separate volume product, so export anything you need before deletion (see lifecycle, storage, and networking).
Common pitfalls
- Forking when you needed reproducibility. A live fork captures the present, including whatever mess the running process made. If the deliverable is a clean, repeatable starting point, stop the machine and package it instead.
- Packaging when you needed warm state. A
.smolmachineboots fast, but it does not carry running processes or CUDA state. If the value is in a loaded model or a mid-task agent, fork the live machine on the same host. - Assuming packages are portable across architectures. Same architecture only (arm64 or x86_64). Plan separate packages per architecture if you serve both.
- Assuming local and cloud network defaults match. Locally networking is off by default. On smol cloud, outbound access is open unless you set
network.modetoblockedorallowCidrs. Check the policy on every machine. - Deleting a cloud machine before exporting data. Stop keeps the filesystem; delete removes it. There are no separate cloud volumes to fall back on.
- Expecting a Smolfile to configure cloud machines. Smolfiles are local-only. For cloud, build an OCI image or reference a
.smolmachine.
Frequently Asked Questions
Does a live fork copy the machine's memory? Yes, effectively. A fork is copy-on-write: forks share the parent's memory pages and diverge on writes, so each fork starts from the parent's exact running state without a full copy.
Can a .smolmachine package boot on any host?
No. It boots only on a host with the same architecture (arm64 or x86_64). Within that constraint it needs no install step and boots in under 200 milliseconds.
Can I snapshot a machine with a loaded CUDA model and restore it later? Not today. A checkpoint captures a running machine but cannot capture CUDA state. Reuse prepared CUDA state through a live fork on the same host instead.
Do my Smolfile settings carry over to smol cloud?
No. A Smolfile configures local machines only. Cloud machines are created from an OCI image or a .smolmachine reference, and outbound network access there is open by default unless you restrict it.
Conclusion
Live forking and packaging solve different reuse problems. Fork a running environment when the value is the present moment: warm caches, loaded models, mid-flight agent state, and many parallel copies needed now. Package a stopped environment when the value is the recipe: a self-contained .smolmachine that boots identically in under 200 milliseconds on any same-architecture host, with no install step. With Smolmachines both paths sit on the same VM model, so you can fork today and package tomorrow without changing tooling. Pick the path that matches what you actually need to preserve, and start with the Smolmachines docs.