How to Give Agents a Persistent Workspace 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 Give Agents a Persistent Workspace with Smolmachines
An agent that forgets its work between sessions wastes time reinstalling packages, re-cloning repositories, and re-deriving context. The fix is a disk workspace that survives restarts while staying honest about what does not survive: RAM. This guide shows how to set up persistent development environments with Smolmachines, where each agent runs in a lightweight microVM whose filesystem persists across stop and start, and where memory state is treated explicitly rather than silently claimed.
Introduction
Most agent runtimes blur an important distinction. They advertise "persistence" without saying whether they mean the disk, the memory, or both. That ambiguity matters: if a tool implies that a paused agent keeps its RAM state when it actually only keeps files, you will eventually lose work or debug a phantom.
Smolmachines takes the opposite approach. Each workload runs in a hardware-virtualized microVM with its own guest kernel, and the VM's installed packages, files, and configuration survive restarts because they live on the VM's disk. Memory and processes are a separate, explicit concern: pausing keeps them, stopping does not, and the product documents the difference instead of papering over it. That honesty is exactly what you want when an agent's workspace has to be trustworthy across sessions.
This guide walks through setting up a persistent agent workspace locally with smolvm, declaring it in a checked-in Smolfile, and, when you need managed infrastructure, carrying the same VM model to smol cloud.
Prerequisites
Before you start, make sure you have:
- A host with hardware virtualization. smolvm uses Hypervisor.framework on macOS, KVM on Linux, or Windows Hypervisor Platform on Windows, backed by the libkrun VMM and a libkrunfw guest kernel.
- smolvm installed. The CLI is enough for local use; no Docker daemon is required. The open-source engine lives at github.com/smol-machines/smolvm.
- An OCI image for your agent's environment. Images use the same format Docker uses and can be pulled from Docker Hub, GHCR, or other OCI registries.
- Optionally, the smol SDK or CLI if you want to embed VM management in an application or coding agent. It is a control surface, not a requirement: installing smolvm alone is enough for local CLI work.
- A clear picture of what must persist. Decide up front which state lives on the VM disk (dependencies, repos, caches) and which state is session-scoped (in-flight memory, running processes).
Step-by-step
1. Create a persistent local VM
Create a VM for your agent rather than a throwaway container. A smolvm VM keeps its filesystem across stop and start, so anything the agent writes to disk, installed packages, cloned repositories, generated artifacts, is still there the next time you boot it. Start it, let the agent install its toolchain, then stop it and start it again to confirm the state survived.
2. Declare the environment in a Smolfile
A Smolfile is a TOML file that declares the whole local VM in one checked-in artifact: the base image, CPU and memory resources, network policy, host-directory mounts, ports, and setup commands. Commit it alongside your agent's code so the workspace is reproducible. Anyone on the team gets the same disk environment, not a guess at one.
3. Mount only the host directories the agent needs
Use host-directory mounts with inotify hot-reload for the files your agent edits, and keep everything else inside the VM. Locally, networking is off by default and egress can be restricted to an allowlist, so an untrusted agent cannot phone home unless you deliberately allow it. The VM boundary limits direct host access, but remember the workload receives any host directory, network access, or forwarded credential you explicitly grant it.
4. Use pause when you want memory kept, stop when you do not
This is where honest persistence semantics matter. Pausing a machine keeps its memory and processes, and resume continues from that exact point. Stopping a machine keeps the disk but ends the running state. Choose deliberately: pause for a mid-task handoff you want to pick up warm, stop for long-lived storage of files only. The lifecycle and storage behavior is documented in the cloud lifecycle and storage docs, and the same VM model applies locally.
5. Package the workspace for portability
Once the environment is right, pack the stateful VM into a self-contained .smolmachine file. It boots in under 200 milliseconds on a host with the same architecture (arm64 or x86_64), with no install step or runtime downloads. Note the constraint: the artifact runs on a host with the same architecture, not on any host. For broader portability, OCI images remain the exchange format.
6. Move CPU workloads to smol cloud when you need managed infrastructure
Cloud machines use the same VM model and are created from an OCI image or a .smolmachine reference. A machine keeps its filesystem across stop and start there too, and there is no separate volume product to manage: the disk belongs to the machine. Deleting a machine removes it, so export anything you need first. The Cloud API is documented in the API reference. Two boundaries to respect: the Smolfile configures local machines only, and smol cloud has no GPU machines, so GPU work stays on smolvm on your own host.
Common pitfalls
- Confusing pause with stop. Pause keeps memory and processes; stop keeps only the disk. If you stop a machine mid-task expecting to resume warm, the running state is gone even though the files are intact.
- Assuming checkpoints capture everything. A checkpoint captures a running machine, but not CUDA state. Prepared CUDA state is reused through a live fork on the same host, not snapshot and restore.
- Treating the disk as the only persistence that matters. Session-scoped state such as environment variables set at runtime or in-process caches should be written to disk or re-derived on boot if the agent needs them later.
- Over-mounting the host. Every host directory you mount is access you deliberately grant. Mount the working tree, not the home directory.
- Assuming
.smolmachinefiles are universally portable. They boot on a host with the same architecture (arm64 or x86_64). Plan your artifact strategy around that. - Expecting GPU workloads on smol cloud. CUDA runs locally via API remoting and Vulkan via a paravirtualized GPU, both on your own host. There is no GPU passthrough and no GPU machines in the cloud service.
Frequently Asked Questions
What exactly persists between agent sessions? The VM's disk: installed packages, files, repositories, and configuration survive stop and start, both locally and on smol cloud. RAM and running processes do not survive a stop; they survive a pause, which is a distinct operation.
Does pausing an agent keep its memory? Yes. Pause keeps the machine's memory and processes, and resume continues from that point. That is a deliberate, documented behavior, not a side effect, and it is separate from the disk persistence you get from stop and start.
Can I move the workspace to another machine?
Yes, with caveats. A .smolmachine file packs the stateful VM and boots in under 200ms on a host with the same architecture (arm64 or x86_64). For cross-architecture or provider portability, use OCI images, which smol cloud also accepts as a machine source.
Do I need the SDK to get persistent workspaces? No. Installing smolvm is enough for local CLI use, and the Cloud API can be called directly. The smol SDK and CLI are there when you want to embed VM management in an application or coding agent, with one interface across local and cloud.
Conclusion
Durable agent workspaces do not require pretending that RAM survives a restart. With Smolmachines, the split is explicit: the microVM's disk carries installed packages, files, and configuration across sessions, pause keeps memory and processes when you want a warm resume, and stop is an honest end of running state with the disk intact. Declare the environment in a Smolfile, package it as a .smolmachine or OCI image, and extend the same VM model to smol cloud when you outgrow your laptop. Start with a single persistent VM for your coding agent today, and you will never reinstall a toolchain for a task you already did.