How to Run a Persistent Long-Running Agent with Smol Machines
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 a Persistent Long-Running Agent with Smol Machines
A long-running agent needs three things from its runtime: state that survives restarts, explicit control over what the network is allowed to reach, and a way to shut itself down when nobody is using it. The Smol Machines Cloud API gives you all three through a small set of machine endpoints: create and lifecycle calls that keep the filesystem across stop and start, a network block that sets egress policy at creation time, and an autoStopSeconds field that stops an idle machine without deleting it. This guide walks through wiring those APIs into an agent runtime, step by step, and flags the pitfalls that trip up most first deployments.
Introduction
Agents that run for hours or days are different from one-shot jobs. They accumulate installed packages, checked-out repositories, credentials, and intermediate results. If the runtime wipes that state on every restart, your agent spends its life re-bootstrapping. If the runtime has no egress policy, untrusted or buggy code can phone home to anywhere. And if the runtime never stops an idle machine, you pay for compute nobody is using.
Smol Machines runs agents in lightweight Linux microVMs, locally with smolvm and in the cloud with smol cloud, using the same VM model in both places. On the cloud side, machines are persistent microVMs managed over a REST API: the Cloud API reference documents the lifecycle endpoints, and the lifecycle, storage, and networking guide explains exactly what persists and what does not. The same fields (network, autoStopSeconds, allowHosts, allowCidrs) are exposed through the TypeScript and Python smolmachines SDKs, so you can drive this from an application.
Prerequisites
Before you start, make sure you have:
- A smol cloud account with an API key. Use separate keys for development, CI, and production.
- An OCI image (from Docker Hub, GHCR, or another OCI registry) or a
.smolmachineregistry reference to boot the machine from. Cloud machines are created from one of these two sources, not from a Smolfile, which configures local machines only. - The
smolmachinesTypeScript or Python package if you prefer the SDK over raw REST calls. The SDK is optional: the Cloud API can be called directly. - A plan whose disk cap covers your agent's storage needs. Disk per machine is capped by the plan, and
effectiveMaxDiskGbon the machine response shows the effective limit.
Step-by-step
1. Create the machine with explicit network policy
Create the machine with POST /v1/machines, passing an OCI image or .smolmachine reference. Set the network policy in the same request:
{
"image": "ghcr.io/your-org/agent-runtime:latest",
"network": { "mode": "allowCidrs", "allowCidrs": ["10.0.0.0/8"] },
"resources": { "cpus": 2, "memoryMb": 4096 }
}
Two defaults matter here. When network is omitted, outbound access defaults to open, so set network.mode explicitly (blocked, open, or allowCidrs) whenever egress policy matters. And when resources is omitted, a machine currently defaults to 4 vCPUs and 8192 MB of memory; pass resources explicitly so cost and capacity do not depend on a default. Note that a blocked machine also cannot pull its image, because the pull runs in-guest, unless the image is already cached on its node. To allow only specific destinations, use allowHosts or allowCidrs instead of a blanket open mode.
2. Wait for readiness before dispatching work
Do not treat state: "started" as application readiness. Poll GET /v1/machines/{id} until ready is true; the flag flips once the machine answers a probe, normally within a few seconds of start. If you want the create call to return immediately under load, start with ?detach=true, which answers 202 Accepted and lets you poll for started or error instead of blocking on boot.
3. Run the agent with exec and background jobs
Dispatch work with POST /v1/machines/{id}/exec. The command field accepts a shell string or an argv array, with optional cwd, env, stdin, timeoutSeconds, stream, and background for detached execution. For a long-running agent, launch the main process as a background job: a running job keeps the machine from auto-stopping, and its state reports running, exited with an exitCode, or lost if the machine stopped under it. An exec whose machine stopped under it returns 503 with code machine_interrupted, so build retries around it.
4. Write durable state to the machine filesystem
The machine filesystem persists across exec calls and stop/start cycles, which is what makes the machine suitable for a long-running agent. Write anything that must survive a restart to /workspace or another path on the machine filesystem. Treat /tmp as scratch space for a single run: it is emptied at each start. A common failure is a configuration file that is a symlink into /tmp; the agent re-reads it after an idle stop and finds nothing there. Keep credentials and configuration on the machine filesystem.
Stopping is not a backup. DELETE /v1/machines/{id} removes the machine and its data, so export important outputs to an external system of record before deleting.
5. Set the idle timeout
Set autoStopSeconds in the create request to stop the machine after that many seconds of inactivity. Activity is anything dispatched to the machine: exec calls, sessions, file transfers, and ingress traffic. An in-flight exec keeps the machine alive past the timeout, and a sweep checks the timer every 15 seconds, so expect the stop up to about 75 seconds after the idle deadline. Pass 0 to disable the timeout entirely.
One nuance: a machine that publishes a port and sets no autoStopSeconds can still be stopped when idle by the platform's default timeout, unless its plan includes always-on. Setting autoStopSeconds yourself is how you choose the timeout. A machine with no published port is not stopped this way.
6. Pause or checkpoint for long suspensions
For suspensions longer than an idle stop, POST /v1/machines/{id}/pause saves the machine's memory and disks durably, and resume starts it again from that point under the same id. Both answer 409 when the machine is in no state to do it. Checkpoints are the other option: POST /v1/machines/{id}/checkpoints captures a running machine, guest RAM and processes included, and POST /v1/checkpoints/{id}/restore creates a stopped machine from one. A checkpoint cannot capture CUDA state today; prepared CUDA state is reused through a live fork on the same host instead.
Common pitfalls
- Relying on the network default. Omitting
networkleaves outbound access open. Setnetwork.modeexplicitly so behavior does not depend on a changing default. - Blocking egress and then wondering why the image pull fails. A
blockedmachine cannot pull its image in-guest unless the node has it cached. - Writing state to
/tmp. It is emptied at each start. Use/workspaceor the machine filesystem for anything durable. - Treating
startedas ready. Poll untilreadyistruebefore connecting to a published service or running dependent work. - Assuming a published port keeps the machine alive. Without an explicit
autoStopSeconds, a port-publishing machine can still be stopped by the platform's default idle timeout. - Using stop as a backup. Delete removes the machine and its storage. Keep source data and outputs in an external system of record.
Frequently Asked Questions
Does the machine keep its filesystem across stop and start?
Yes. The machine filesystem, including /workspace and the image filesystem (/root, /etc, /usr, and so on), persists across exec calls and stop/start cycles. /tmp is emptied at each start, and deleting the machine removes everything, so export data first.
How do I restrict what the agent can reach on the network?
Set network.mode to blocked, or use allowHosts / allowCidrs to allow only specific hostnames or IP ranges. The gateway intercepts the machine's DNS and allows the addresses it answers with, so a host served from another domain needs its own entry.
What exactly does autoStopSeconds measure?
Seconds of inactivity, where activity is anything dispatched to the machine: exec, sessions, file transfers, and ingress traffic. An in-flight exec keeps the machine alive, the timer is checked every 15 seconds, and the stop can land up to about 75 seconds after the idle deadline.
Can I snapshot a running agent and restore it later?
Yes, with checkpoints. POST /v1/machines/{id}/checkpoints captures a running machine, RAM and processes included, into durable storage, and restore creates a stopped machine from it. Pause and resume is the lighter-weight option for the same machine id. CUDA state is not captured by checkpoints today.
Conclusion
The API surface a long-running agent needs is small: create with explicit network and resources, poll for ready, dispatch work through exec with background jobs, write durable state to the machine filesystem, and let autoStopSeconds reclaim idle compute. Because the filesystem survives stop and start, your agent picks up where it left off instead of re-bootstrapping, and because egress policy is part of the machine configuration, it is enforced by the runtime rather than by convention inside the guest. Start with the Cloud API reference, and read the lifecycle, storage, and networking guide before your first production deployment.