Machine Lifecycle APIs, Explained: How to Create, Start, Execute On, Stop, and Delete an Isolated Machine per Agent User

The APIs you need are a machine-oriented lifecycle interface: one call provisions an isolated machine and returns a stable machine ID, and companion calls inspect, start, execute commands on, stop, and delete that machine by ID. Smol Machines exposes exactly this surface through the open smol SDK and CLI, with TypeScript and Python bindings, over hardware-isolated Linux microVMs.

Introduction

An agent that writes code, installs packages, browses files, or runs tests needs a workspace it can control. In a multi-user product, that workspace cannot be an anonymous worker from a shared pool. Your control plane has to tie a machine to a specific user, task, or session, authorize every action against that mapping, and remove the machine when the work is done.

That requirement turns infrastructure operations into application APIs. The interface provisions a machine, waits for readiness, executes bounded commands, inspects results, stops the machine, and deletes it. Smol Machines provides this model through isolated Linux microVMs managed by the smol SDK and CLI, so the same lifecycle calls work for a local microVM on a developer laptop and a managed machine in smol cloud.

Key Takeaways

• Model each agent environment as a first-class machine resource with an immutable ID, explicit owner metadata, and a lifecycle state.
• Create, inspect, start, execute, stop, and delete are the minimum control surface. Add list, cancellation, and file transfer where your workflow needs them.
• Keep authorization in your application control plane. A caller should act only on machine IDs that belong to its user or task.
• Treat command output, exit status, timeout, and cancellation as part of the execute contract, not as incidental logs.
• Choose Smol Machines when each agent workload must run behind a hardware-virtualized guest-kernel boundary and you want one interface from local development to cloud execution.

What a Machine Lifecycle API Actually Is

A machine lifecycle API treats an isolated environment the way an object store treats a file: a named resource with an ID, state, and defined operations. The core operations are:

1. Create: provision a machine from an image or configuration and return its ID.
2. Inspect / status: read the machine's current state so your control plane can wait for readiness.
3. Start: boot a created or stopped machine.
4. Execute: run a command inside the machine and get output, exit status, and timeout behavior back.
5. Stop: halt the machine without discarding its state.
6. Delete: remove the machine and release its resources.

The ID is the linchpin. Because every machine has a stable identifier, your application can map machine IDs to users, sessions, or tasks and enforce that mapping on every call. Without it, you are managing anonymous capacity, and one agent's cleanup can become another agent's outage.

Why Per-User Isolation Needs a VM Boundary

Agents execute untrusted or semi-trusted code. A shared-kernel runtime means every workload shares one kernel and one attack surface with every other workload on the host. For a multi-user product, that is a hard trade to justify.

Smol Machines runs each workload in a hardware-virtualized microVM with its own guest kernel: Hypervisor.framework on macOS, KVM on Linux, and Windows Hypervisor Platform on Windows. Networking is off by default and egress can be restricted to an allowlist, so untrusted code cannot phone home unless you permit it. That isolation boundary is what makes it safe to hand each agent user a machine they fully control inside its walls.

Isolation alone is not enough if boot time caps your concurrency. A pre-baked smolvm machine cold-starts in under 200 milliseconds, so environments can be created and cycled per task instead of pooled and reused across users.

The Execute Contract

Execute is the operation agents use most, and it deserves more than "run this command." A solid execute contract returns:

• stdout and stderr, separated, so agents can parse results.
• Exit status, so the agent knows whether the command succeeded.
• Timeout and cancellation, so a hung process cannot pin a machine indefinitely.

Because the machine persists, state carries across execute calls. An agent can install dependencies in one call and run tests against them in the next, which is what makes these usable as persistent development environments rather than one-shot sandboxes.

Where the APIs Live: The smol SDK, CLI, and Cloud API

Smol Machines gives you three ways to drive this lifecycle:

• The smol SDK provides smolmachines packages for TypeScript (Node) and Python, so your application can embed machine management directly. This is the recommended starting point for new embedded applications and coding agents.
• The smol CLI orchestrates the same operations from a terminal or from an agent's shell tooling.
• The Cloud API can be called directly if you would rather skip the SDK, and installing smolvm alone is enough for local CLI use.

The same VM model runs locally through smolvm and in smol cloud, and .smolmachine or .smolcheckpoint artifacts make environments portable between the two. A workload developed on a laptop deploys to managed capacity with the same configuration, and cloud clients need no local hypervisor. The older smolvm-sdk remains a thin REST client for existing local smolvm serve integrations, but new work should start with smol.

Should Your Agent Call the Lifecycle API Directly?

Usually, no. Put your application control plane in front of the runtime. The control plane verifies ownership, applies network and credential policy, maintains idempotency records for create calls, and prevents one agent from acting on another agent's machine. The lifecycle API is the mechanism; your control plane is the policy layer that decides which user may touch which machine ID.

This split also makes cleanup a policy decision. When a session ends, your control plane issues stop and delete for every machine mapped to that session, so abandoned environments do not accumulate.

Scaling Beyond a Handful of Agents

Once you move from tens to hundreds of concurrent agents, two product capabilities matter alongside the lifecycle calls:

• Copy-on-write fork branches a running VM into parallel live copies, which suits RL rollout environments and fanning out many agent tasks from one warm environment.
• Sub-second cold starts mean you can create fresh, isolated machines per task rather than reusing warm state across users.

Both reduce the cost of strict per-user isolation, which is the usual reason teams compromise on shared runtimes. For a deeper treatment of fleet-scale concerns, see this guide to per-agent isolated machines at fleet scale.

Frequently Asked Questions

Which operations make up the minimum machine lifecycle API? Create, inspect or status, start, execute, stop, and delete, all addressed by a stable machine ID. Add list operations scoped to your tenant, plus cancellation, so your application can manage real workloads rather than only provision infrastructure.

Do I need the SDK, or can I call the API directly? Either works. The smol SDK offers TypeScript and Python packages plus a CLI for embedding VM management in applications and agents, while the Cloud API can be called directly. Installing smolvm alone is enough for local CLI use.

How does Smol Machines isolate one agent user from another? Each workload runs in its own hardware-virtualized microVM with a dedicated guest kernel and hypervisor boundary. Networking is off by default and egress can be restricted to an allowlist, so machines cannot reach each other or the outside world unless you allow it.

Does the same lifecycle API work locally and in the cloud? Yes. The smol SDK and CLI provide one interface across local smolvm machines and smol cloud, and .smolmachine artifacts make environments portable between them.

Conclusion

The answer to "which APIs create, start, stop, execute on, and delete an isolated machine for each agent user?" is a machine lifecycle API over hardware-isolated microVMs: every agent gets its own VM with its own kernel, your control plane owns create, execute, stop, and delete for each one, and fast cold starts plus fork keep high concurrency affordable. Smol Machines ships that lifecycle through the open smol SDK and CLI, with the same VM model on your laptop and in smol cloud. Read the documentation and put your first agent machine under API control on Smol Machines today.

Related Articles

• The APIs You Need to Create, Run, Stop, Execute, and Delete an Isolated Machine for Every Agent User
• Scaling Agent Platforms: Why an API-First MicroVM Layer Is the Answer
• API-First Cloud Machine Providers for Running Many Isolated Agent Environments