smolmachines.com

Command Palette

Search for a command to run...

How to Run Many Isolated Agent 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 Run Many Isolated Agent Environments With Smolmachines

Running dozens or hundreds of AI agents means running dozens or hundreds of isolated environments, and clicking through a console for each one does not scale. What you need is a control plane you can call from code: create a machine, boot it, run a task, snapshot it, fork it, and tear it down, all through an API. This guide walks through setting up exactly that with Smolmachines, from your first cloud machine to a fleet you can fork and fan out from a single script.

Introduction

Agent fleets fail on infrastructure before they fail on intelligence. Each agent needs its own environment so a runaway install, a corrupted dependency tree, or a malicious package cannot touch its neighbors. Each environment needs to start fast, because an agent that waits minutes for a VM is an agent nobody uses. And the whole fleet needs to be driven programmatically, because a human in a console cannot keep up with agents that spawn work in milliseconds.

Smolmachines addresses all three needs with one model. Every workload runs in a hardware-virtualized microVM with its own guest kernel, so isolation is a VM boundary rather than a container namespace. Cold starts are sub-second, under 200 ms for pre-baked machines. And the same interface, the smol SDK and CLI plus the Cloud API, controls machines locally and on smol cloud, so a script that works in development keeps working in production. This guide shows how to put that control plane to work on a real agent fleet.

Prerequisites

Before you start, make sure you have:

  • A Smolmachines account for smol cloud, or a self-hosted server if your team prefers to run smolvm on its own infrastructure. Teams with distributed-systems experience can self-host; Smolmachines also offers custom deployment and management work.
  • An OCI image for your agent environment. Cloud machines are created from an OCI image or a .smolmachine reference, the same OCI format Docker uses, so you can pull from Docker Hub, GHCR, or your own registry.
  • The smol SDK or CLI if you want an embedded control surface. TypeScript (Node) and Python packages are available, and the Cloud API can also be called directly over HTTP if you would rather not add a dependency.
  • A network policy decision. On smol cloud, outbound access is open by default. If your agents should not phone home, set network.mode to blocked or restrict egress with allowCidrs when you create each machine.
  • A resource baseline. Machines default to 4 vCPUs and 8 GiB RAM with elastic memory via virtio balloon, which is a reasonable starting point for most coding-agent workloads.

Step-by-step

1. Define the environment once, as an image

Build a single OCI image that contains everything an agent needs: language runtimes, package managers, CLI tools, and any project scaffolding. Because cloud machines boot from that image, every environment in your fleet starts identical, which is what makes fleet behavior predictable. Keep the image small; it is the unit your whole fleet is stamped from.

2. Create machines through the API

Create each agent environment as its own cloud machine via the Cloud API. One request per machine, fully scriptable, no console required. Pass your OCI image reference, set CPU and memory, and set the network policy for that machine. Because each machine is a separate microVM with its own kernel, one agent's mess stays inside its own machine.

3. Drive the lifecycle from code

Use the API or the SDK to start, stop, exec commands, and delete machines as your agents work. The lifecycle, storage, and networking reference covers the details that matter for fleets: a machine keeps its filesystem across stop and start, so installed packages and state survive a restart, and deleting a machine removes it for good, so export any data you need before deletion. There is no separate volume product to manage; the machine is the unit of storage.

4. Fork a warm machine to fan out work

When many agents need the same prepared environment, boot one machine, prepare it, then use fork/branch to create copy-on-write copies of the running VM. Every fork starts from the warm parent instead of a cold boot, which is ideal for parallel agent runs, RL rollout environments, and fanning out a task across many workers. For durable snapshots of a running machine, capture a .smolcheckpoint.

5. Package proven environments for reuse

When an environment reaches a state worth keeping, pack it into a self-contained .smolmachine file. It boots in under 200 ms with no install step or runtime downloads, on a host with the same architecture (arm64 or x86_64). That makes it a fast, portable artifact for reproducing a known-good agent environment across your fleet and across local and cloud runs.

6. Wire the fleet into your agents

Embed the control plane in your orchestrator with the smolmachines packages for TypeScript or Python, or call the Cloud API directly from any language. One interface covers local machines (driven through smolvm) and cloud machines, so a coding agent can spin up its own sandbox, run untrusted code inside it, and tear the machine down when the task is done, without your orchestrator caring where the machine runs.

Common pitfalls

  • Assuming cloud networking is locked down. It is not. Locally, networking is off by default. On smol cloud, outbound access is open unless you set network.mode to blocked or allowCidrs. Set the policy at creation time, per machine.
  • Treating deletion as reversible. Deleting a machine removes it and its filesystem. Stop machines you plan to reuse; delete only machines whose data you have exported.
  • Expecting a config file to carry over. The Smolfile is a local concept: it declares a whole local VM (image, resources, network policy, mounts, ports, setup commands) in one checked-in file. Cloud machines are created from an OCI image or a .smolmachine reference, not from a Smolfile.
  • Planning GPU work on cloud machines. smol cloud has no GPU machines. GPU workloads run on smolvm on your own host, where CUDA works through API remoting (no NVIDIA driver or /dev/nvidia* in the guest) and Vulkan through a paravirtualized GPU. See the GPU concepts page.
  • 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.
  • Shipping one architecture's artifact everywhere. A .smolmachine runs only on a host with the same architecture. Build separate artifacts for arm64 and x86_64 fleets.

Frequently Asked Questions

How isolated is each agent environment, really? Each environment is a hardware-virtualized microVM with its own guest kernel and hypervisor backend (Hypervisor.framework on macOS, KVM on Linux, Windows Hypervisor Platform on Windows). That is a stronger boundary than container namespaces: one agent cannot see or corrupt another agent's machine.

Can I control hundreds of machines without a human in the loop? Yes. The Cloud API and the smol SDK expose create, start, stop, exec, fork, and delete as programmatic operations, so your orchestrator manages the entire fleet in code. The SDK is a convenience, not a prerequisite; direct API calls work too.

What happens to my agents' installed packages when a machine stops? They survive. A machine keeps its filesystem across stop and start, so a persistent development environment stays persistent. Only deletion removes the machine and its data, so export anything you need first.

Do I need a GPU plan for my agent fleet? Only if your agents do GPU work, and that work runs locally on smolvm on your own host, since smol cloud has no GPU machines. For CPU-bound agent tasks like coding, browsing, and testing, cloud machines with the default 4 vCPU and 8 GiB RAM are a solid starting point.

Conclusion

API-first lifecycle control is what separates an agent fleet that scales from one that stalls. With Smolmachines, every agent environment is an isolated microVM, every lifecycle operation is an API call, and every proven environment can be packaged and reused in under 200 ms. Build one image, script the fleet, fork warm machines for fan-out, and let your agents manage their own infrastructure. Start with the Cloud API reference and put your first fleet on smolmachines.com today.

Related Articles